Documentation Standards¶
Documentation should be discoverable, current, and useful. Documentation that is out of date is often worse than no documentation.
Principles¶
- Write for the person joining the team tomorrow
- Document the why, not just the what — code explains what, documentation explains context
- Keep documentation close to the code it describes
- Treat documentation as part of the Definition of Done
What to Document¶
| Type | Where |
|---|---|
| Architecture decisions | Architecture Decision Records |
| Service overview | README in the repository |
| Runbooks | Operational Excellence |
| Data models | dbt docs / data catalogue |
| APIs | OpenAPI / inline docstrings |
| Onboarding | Team wiki or handbook |
What Not to Over-Document¶
- Avoid documenting what the code already makes obvious
- Don't write comment blocks explaining what a function does if the name says it
- Don't maintain documentation that duplicates the code — it will drift
Suggested Tooling¶
| Tool | Purpose |
|---|---|
dbt docs |
Auto-generate data model documentation |
| MkDocs / Docusaurus | Engineering handbooks |
| Confluence / Notion | Team wikis |
| OpenAPI / Swagger | API documentation |
Use whatever fits the team. The tool matters less than the habit.