search

hasadna / open-bus

:bus: Analysing Israel's public transport data
93 stars 29 forks source link

Document siri_rt.log v1 (current version) #184

Open cjer opened 5 years ago

cjer commented 5 years ago

Documentation should include the following:

  1. file format
  2. all fields, with their names as they appear in SIRI response
  3. Reference to relevant official documentation (preferably from MOT if exists)
  4. the corresponding GTFS fields for relevant fields
  5. how fields appear in splunk (names and format)
  6. an example file in our git (include SIRI request and response example files too)

Anything else? We also need to make a general decision about where to put this kind of documentation (wiki/ markdown in code repo / separate documentation website?)

cjer commented 5 years ago

For documentation purposes, since MOT tends to change their pages and not keep old versions, I archived their current versions in the Internet Archive (maybe we should do this periodically too)

evyatark commented 5 years ago

Also - where the files are located (or at least a reference to an issue/wiki page that describes where they are located. Also - reference to some code that reads such file (preferably in both Java and Python)

adiwaz commented 5 years ago

I started working on this documentation issue.

Location: I have opened a wiki page to host the information: "Bus Real Time (SIRI) Data Documentation". If you have comments/ideas for where is the best place to have this info please share.

adiwaz commented 5 years ago

Update - I put a link in the work-in-progress SIRI documentation wiki page to the siri_retriever README that was written by @evyatark : https://github.com/hasadna/open-bus/tree/siri-doc/siri

adiwaz commented 5 years ago

@cjer @evyatark I need your help with information about: 1. What are the raw results that siri retriever gets? 2. What are the stages between the raw answers and the Splunk table?

Feel free to write it here / link to where it is documented / fill it directly in the wiki page: https://github.com/hasadna/open-bus/wiki/Bus-Real-Time-%28SIRI%29-Data-Documentation.

Thanks!

adiwaz commented 5 years ago

Update: We decided that we will have The data flow documentation from MOT to our servers (both siri and gtfs) documented in wiki, and the actual variables will be documented in the relevant code that generates the data tables. This issue is going to be reorganized to affect this decision.