Documentation System
Build documentation that stays current and actually gets used.
Usage
- Audit existing documentation: what exists, what's missing, what's outdated
- Define documentation types: tutorials (learning-oriented), how-to guides (task-oriented), reference (information-oriented), explanations (understanding-oriented)
- Choose tooling: docs-as-code (Markdown + Git), wiki (Confluence, Notion), or generated (Swagger, TypeDoc)
- Establish writing standards and templates for consistency
- Create a maintenance process: ownership, review cadence, freshness indicators
Examples
- Diataxis framework (4 types of documentation): Tutorials: "Getting started with our API" (step-by-step for beginners). How-to guides: "How to authenticate with OAuth2" (task-specific for practitioners). Reference: "API endpoint documentation" (comprehensive, accurate, auto-generated where possible). Explanation: "Why we chose event sourcing" (architectural decisions, context)
- Docs-as-code workflow: Markdown files live alongside code in the same repo. PRs that change code must update relevant docs (enforced by CI check). Build docs with MkDocs/Docusaurus on merge to main. Deploy to docs.yoursite.com automatically. Benefits: version-controlled, reviewed, always matches the code version
- README template: Project name + one-line description. Quick start (copy-paste to working state in under 5 minutes). Prerequisites. Installation. Configuration. Usage examples (3+). API reference (or link to it). Contributing guide. License. Troubleshooting / FAQ. Keep the README under 500 lines — link to detailed docs for depth
Guidelines
- The biggest documentation problem is not missing docs — it's outdated docs. Wrong documentation is worse than no documentation
- Every doc needs an owner (person or team) and a review date. Add "Last reviewed: YYYY-MM-DD" to the top of every page
- Write for the reader, not the writer. The person reading your docs is in a different context than you — spell out assumptions
- Screenshots become outdated fastest — use them sparingly. Code examples and text descriptions are more maintainable
- Good documentation has examples. Great documentation has examples that actually work (test them in CI)
- The best time to document is right after you figure something out, while context is fresh — not "later" (later never comes)