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
| Reference | Description |
|---|---|
| readme-guide.md | README templates, section patterns, badges |
| api-docs.md | API documentation patterns, OpenAPI integration |
| adr-guide.md | Architecture Decision Record format and workflow |
| diagrams.md | Mermaid diagram patterns for common scenarios |
| readme-template.md | Template for project README files |
| adr-template.md | Template for Architecture Decision Records |