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