Add GTFS-RT Best Practices documentation

[minhhpham]

Refer to https://github.com/MobilityData/Tasks/issues/6.

All Markdown files in en/ directory are combined into index.md by running en/combine.sh.

Do not change index.md directly - change the other .md files and re-generate index.md.

I gathered ideas of best practices by searching for message names in my emails to look for discussions and from the GTFS Realtime Validator Rules.

TODO:

• Scott review RT proposals accepted since Oct 3 2019 to see if they change best practices (Spec updates since first Best Practices draft #3)
• TripUpdate timestamps - see Proposal: Add TripUpdate.is_trip_finished google/transit#241 (comment). This is being addressed in Clarification of TripUpdate.timestamp google/transit#263 so we don't need to address here.
• Header timestamp definition - move to Additional items to triage for best practices or spec inclusion #5
• Update Alert docs based on TripDescriptor clarification of referencing only a single trip instance (Clarify TripDescriptor as referencing a single trip instance google/transit#163)
• Add transport protocol suggestions, API keys (similar to GTFS)
• HTTP not modified - The web-server hosting GTFS data should be configured to correctly report the file modification date (see HTTP/1.1 - Request for Comments 2616, under Section 14.29).
• Say that endpoints shouldn't need to define special HTTP accept headers to get PB response back
• Remove references to NO_SERVICE in best practices - these need further community discussion (see Additional items to triage for best practices or spec inclusion #5)
• The best practice would be to provide both the TripUpdate with the dates for the next 7 days as CANCELED as well as an Alert with NO_SERVICE that can be shown to riders explaining the detour.
• Transit App best practice about alerts for closed/modified stops - https://resources.transit.app/article/182-stop-alerts - Some were added in 7555c57, but others need to be considered in Additional items to triage for best practices or spec inclusion #5.
• If all stops in a trip are SKIPPED, the trip should be canceled instead of showing a TripUpdate with all stop_time_updates being SKIPPED
• Sean review "FeedEntity.md"
• Sean review "FeedHeader.md"
• Sean review "Frequency-based.md"
• Sean review "introduction.md"
• Sean review "Position.md"
• Sean review "StopTimeEvent.md"
• Sean review "StopTimeUpdate.md"
• Sean review "TripDescriptor.md"
• Sean review "TripUpdate.md"
• Sean review "VehicleDescriptor.md"
• Sean review "VehiclePositions.md"
• Scott and Sean review Google's current RT requirements and see if we're missing anything important here (anything new since Oct 2019) - https://support.google.com/transitpartners/?hl=en#topic=3521043. In particular, Google's requirements for providing a VehiclePosition feed - https://support.google.com/transitpartners/answer/9047739?hl=en.

EDIT April 1, 2021 - Some checkboxes that require further community discussion have been moved to #5 for further analysis outside this PR

[giocorti]

Thanks for the draft! In addition to my inline comments, I have a few suggestions below:

• "GTFS-realtime" and "GTFS-rt" are used interchangeably. I think we should just pick and use one.
• It looks like fields with no recommendations have also been included. Can we eliminate these fields before publishing the final version in order to make the document more concise?

Let me know what you think.

[minhhpham]

Thanks @giocorti! I pushed a new commit with the changes you suggested.

• I changed all "GTFS-rt" into "GTFS-Realtime".
• I would keep the fields with empty recommendation for now as placeholders for more suggestions. Other reviewers can look at the fields and may think of some recommendations to add.
• We will need to discuss with MobilityData group about GTFS-Realtime Best Practices Working Group.

[heidiguenin]

Some suggestions and questions.

[barbeau]

Needs to be updated based on how we decide to get community input on this.