📄🚀 – Expand documentation’s architecture section

[gabriel-korbato]

Describe the feature you want and how it meets your needs or solves a problem
New TIDES users will want and need to understand how to put their transit agency's data into TIDES format, and part of that is understanding what TIDES table to use for each type of data. In addition, they will have questions such as:

• How should I handle multiple sources of AVL data for the same fleet?
• How should I handle different versions of the same data (for example, raw vs. cleaned, or incomplete vs. complete)

The current documentation section is divided into architecture and table schemas. The architecture section has a list of tables and the relationship between them, but for a particular use case or configuration. A high-level description of the framework and a discussion of different possible use cases and configurations is missing. Users can refer to the G-18 TCRP report but that cannot be updated and may not cover some details that are important for implementing TIDES.

Describe the solution you'd like
Draft a high-level description of the framework and a discussion of different possible use cases, discuss it as a group, and add it to the architecture section of the documentation.

[botanize]

I think it would be great to have a better introduction, especially one that includes motivating examples. The two examples you gave would fit well in a (much talked about, but unimplemented) best practices section.

I think a structure like this makes sense:

• Introduction: what is TIDES, motivation, examples
• Architecture: tables and the relationships among tables
• Table Schemas: table definitions and descriptions
• Best practices / FAQ: using TIDES as a format throughout the data processing pipeline, multiple sources, extensions

Other than a few motivating examples, see #32, I don't want to get into the trap of attempting to list all of the possible uses and configurations. This is a spec for data, not for processing it. The idea is to enable tools to work across agencies, so it is the responsibility of the tool maintainer to describe its capabilities and requirements.

[jlstpaul]

Now is the time to create a Best Practices section of the Documentation

• Build initial content in Google doc here
• Create /docs/best-practices.md from Google doc
• Modify scripts to add Best Practices section to documentation site