usdot-jpo-ode / wzdx

The Work Zone Data Exchange (WZDx) Specification aims to make harmonized work zone data provided by infrastructure owners and operators (IOOs) available for third party use, making travel on public roads safer and more efficient through ubiquitous access to data on work zone activity.
Creative Commons Zero v1.0 Universal
89 stars 62 forks source link

Add and maintain object diagrams for each feed #235

Closed j-d-b closed 1 year ago

j-d-b commented 2 years ago

Background

Prior to WZDx v4.0, the team maintained an object diagram (it is still in the repository) for the WZDxFeed. However, with the addition of two new feeds in WZDx v4.0, there were not enough team members with availability or knowledge of using the diagram software to create the object diagrams for the v4.0 feeds.

Proposal

Part of the issue was that the objects in the object diagram contained the full list of properties, so it was onerous to remove and add to them, especially if one was unfamiliar with the diagram software and text formatting.

I propose that we add and maintain object diagrams, but that the diagrams show just the objects and how they relate without showing the properties of each object. The user can get that information from the specification documentation. This would greatly decrease the amount of work to create the diagrams and there would be much less need for updates while still providing value.

sergebeaudry commented 2 years ago

Agreed. Was useful but I understand the pain and the information will be one click away with the proposal

j-d-b commented 2 years ago

In addition, the high-level description of each object could be added, instead of listing all the properties.

j-d-b commented 1 year ago

Implemented in #330.