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