Add PDF of v4.0 to documents

[mark-mockett]

Add a PDF version of v4.0 to the documents folder for reference.

[j-d-b]

It's tough to review this, because it is very long and effectively a copy of the specification but in a format that's impossible to programmatically check against the "real" specification. Personally, I'd be hesitant to recommend that anyone learn the specification from this copy or develop a feed using it because it has not gone through the same review process as every line of code/documentation in the GitHub repo.

Thus, I'm wondering, did some agency specifically request a PDF version, such that we gain adoption from providing it? If so, I think it may be worthwhile to research and develop a way to programmatically generate a PDF from the markdown files to ensure that the content is exactly the same as in the repo.

Reviewing a manually created PDF thoroughly will be a large effort and will need to be done on every specification release—a large effort for something that has the potential to create issues. Perhaps this document you put together could be something that is handed out on request, but not hosted in the repo or specifically advertised. Let me know what you think of my concerns and if that approach is reasonable.

[tfoster-vm]

Another possible solution is to reference the latest version of the WZDx and/or the SWZDeviceFeed in a simple paragraph. We have shared wording similar to the following for agency's to consider using to require these feeds:

_All Smart Work Zone devices and their remote management software shall provide a public GeoJSON/API feed (updated at least once a minute with any new information) conforming to the latest version of the FHWA’s Work Zone Data Exchange (WZDx) and its associated SWZ Field Device Feed formats as well as make the feed publicly available to any Agency-approved third parties. The SWZ Field Device feed shall include the required Core Details for the SWZ Field Device feed and Device Types. In addition the feed should provide as many as possible Optional Core Details and Optional SWZ Field Device Type parameters as possible. The data feeds shall be made active and be pre-approved before the corresponding SWZ Field Devices are fully approved. The SWZ Field Device Feed for any SWZ field devices shall include the following optional elements (at a minimum); Device Name, Current Display Messages (static & dynamic), Traffic Sensor average speeds (for 1-minute intervals) traffic counts (veh/hour) and Device Status (on/offline). Any display device that is ACTIVE shall be included in the feed. The feed shall also include the and when possible, on Interstate and State Highway routes.

I am confident this wording can be improved upon, but it might help achieve the intent and simplify the referencing to the most current WZDx and SWZDeviceFeed. Comments are welcome.

[mark-mockett]

Thus, I'm wondering, did some agency specifically request a PDF version, such that we gain adoption from providing it? If so, I think it may be worthwhile to research and develop a way to programmatically generate a PDF from the markdown files to ensure that the content is exactly the same as in the repo.

@j-d-b Yes, Mahsa created this document in response to requests from a couple of DOTs that have blocked GitHub on their computers. Obviously storing it here is still inaccessible to those users but makes it easier for anyone else in the community to share with others in similar situations. More broadly, I think it's reasonable to have a "GitHub-first, but not GitHub-only" approach to sharing the WZDx spec.

I agree that the PDF is not a recommended way to learn about the specification. We can (and probably should) add a disclaimer on the /docs readme that the PDF version is not the official version of the specification.

I also agree that it's difficult and time consuming to review, If you'd like me to request someone else to review, just let me know.

[natedeshmukhtowery]

@tfoster-vm I like the idea of a clear summary paragraph.

@j-d-b if you have any suggestions for auto-generation of a PDF from the spec content on github I think that would be brilliant. Mahsa has been instrumental in creating a clean, streamlined PDF version for the last few releases - which I'm sure is appreciated by those relying on it - but even a messy auto-generated PDF that contains the necessary content for WZDx adoption is better than no PDF, which is the likely reality for future releases.

[j-d-b]

@natedeshmukhtowery The PDF looks great (on skimming), thanks @Mahsa-Ettefagh, I did not mean to downplay the effort to create it.

The auto-generated PDF would surely not be as aesthetic.

I will put this on the issue backlog. Added: #282.

[j-d-b]

@mark-mockett

requests from a couple of DOTs that have blocked GitHub on their computers

That's a good reason to have an alternative way to share the specification, thanks for that.

If you'd like me to request someone else to review, just let me know.

I will give it a shot, I just don't trust myself (or most humans, really) to not miss issues if there are any, which is why I think this is problematic.

We can (and probably should) add a disclaimer on the /docs readme that the PDF version is not the official version of the specification.

I agree and also think that disclaimer should be added to the PDF. Can you make that change to the document in this feature branch? That would resolve a lot of my concerns and decrease the requirement of a precise review.

[benafischer94]

@natedeshmukhtowery I mentioned on #282 that using something like sphinx combined with the spec md and some static restructured text files should help get most of the way to an accurate PDF and read-the-docs style documentation. Some agencies may have GH blocked, but still allow access to Read the docs By using a build process with sphinx it would help to keep the docs always up to date with the current version, and allow for both HTML and PDF versions to be uploaded either to RTD or another location.

[natedeshmukhtowery]

@benafischer94 that would be great. Thanks for jumping in on this.

[benafischer94]

I should be able to get a start on this this weekend and submit a draft sample.