Documentation
Create clear, maintainable technical documentation that serves your audience.
Key Principles
- Documentation as code — docs live with code, version with code, review with code
- Audience-first writing — write for who's reading, not what you know
- Maintainability over completeness — inaccurate docs are worse than no docs
- Link to source of truth — don't duplicate information across docs
Quick Start Checklist
- Identify documentation type (README, API docs, ADR, user guide)
- Determine audience (all users, developers, team, contributors)
- Follow type-specific template from references
- Include working examples (test them!)
- Link to related documentation
Documentation Types
| Type | When to Use | Audience |
|---|
| README | Project entry point | All users |
| API Docs | Endpoint reference | Developers |
| ADR | Major decisions | Team/future devs |
| User Guide | Task completion | End users |
References
