📝 Documentation Standards

Structuring and maintaining project documentation for clarity and longevity.

Documentation types

Type	Purpose	Audience
PRD (Product Requirements)	Define what to build and why	Product, Engineering, Design
Technical spec	How to build it	Engineering
API docs	How to use the API	Developers, integrators
Runbook	How to operate and troubleshoot	Ops, on-call
Decision log	Record of key decisions	Everyone
Changelog	What changed and when	Users, stakeholders

Writing principles

• Start with the conclusion — Lead with the "what" and "why"
• Use plain language — Write for the least technical reader
• Structure with headings — Scannable over readable
• One source of truth — Avoid duplicating information
• Date everything — Add "last updated" to living documents

Document lifecycle

1. Draft — Work in progress, open for feedback
2. Review — Shared with stakeholders for input
3. Approved — Final version, ready for reference
4. Archived — No longer current, kept for history

Templates to maintain

• Project brief (1-pager)
• Sprint review summary
• Decision record (ADR format)
• Post-mortem / incident report
• Handoff document