-
Notifications
You must be signed in to change notification settings - Fork 344
Documentation Standards
All active debate should be done on the mailing list so that everyone involved in the project is aware of conversations. Feature proposals typically take the form of a PR that adds a blueprint, but the mailing list should be notified so that everyone who wants to weigh in is made aware of where to do that. The discussion can then take place on the PR, but all project-level decisions must go through the mailing list.
Also, the meeting notes and agenda of Traffic Control working groups should be made into threads on the appropriate mailing list (usually dev), for open discussion and posterity.
This wiki is for documenting process and practices of the project.
When creating or editing wiki pages, consult these guidelines.
- Leave hierarchy names such as “Traffic Ops” out of titles since this is implied by hierarchy above the section and there is no need to repeat it.
- Start section names with a noun that is most related to the topic, instead of action verbs, e.g. "Access Control" is preferred over "Controlling Access".
- Key words in section titles are critical to making search easier, e.g. "Access Control and Tenancy" is preferred over just "Access Control" (where appropriate).
- Review existing section names for established patterns before creating new ones.
The official documentation (housed in /docs) is for documenting the software itself, how to use it, how to configure it, etc.
Guidelines for contributing to the project (e.g. linting settings, code conventions) should go in the CONTRIBUTING.md file at the repository's root. This should contain repository-wide guidelines, and any guidelines specific to a certain tool or component should be linked to from here - probably in their own README somewhere.