Contributing

This handbook only works if it's accurate and easy to follow. Keep pages short, plain, and current.

Principles

• Write for a new teammate. Plain language, second person, sentence-case headings.
• High-level, not exhaustive. Capture how the work actually gets done, not every click.
• One page, one purpose. Put it in the team or project type that owns it.
• Keep it true. When the work changes, change the page first.

Add a team page

1. Copy _page-template.md into the right folder under teams/.
2. Fill in the frontmatter and every section.
3. Add the page to nav: in mkdocs.yml.

Add a project type

1. Copy _project-type-template.md into how-we-run-projects/.
2. Fill it in and add it to the project-type menu on the hub and to nav:.

Preview your change

pip install -r requirements.txt
mkdocs serve          # http://127.0.0.1:8000
mkdocs build --strict # must pass with zero warnings before you open a PR

CI runs the same mkdocs build --strict plus a link check on every PR.