Documentation as Code
Practice of treating documentation with the same tools and processes as code: versioned in Git, reviewed in PRs, and automatically generated when possible.
What it is
Documentation as Code is the practice of treating documentation like code: it lives in the same repository, is versioned with Git, reviewed in pull requests, and automatically generated/validated in CI.
Principles
| Principle | What it means | Example |
|---|---|---|
| Colocation | Docs near the code they document | README per package, JSDoc on functions |
| Versioning | Documentation evolves with code | Docs in same repo, same PRs |
| Automation | Generate docs from code when possible | TypeDoc, Swagger/OpenAPI, Storybook |
| Validation | Verify links, examples, format in CI | Markdown lint, link checker in CI |
Tools
| Tool | Use |
|---|---|
| Markdown | Universal format |
| MDX | Markdown + React components |
| Docusaurus | Documentation sites |
| Storybook | Component documentation |
| TypeDoc/JSDoc | Docs generated from code |
| OpenAPI | Generated API docs |
Connection with llms.txt
The llms.txt standard is documentation as code optimized for AI agents — a Markdown file describing the project for LLM consumption.
Why it matters
Documentation that lives separately from code inevitably becomes outdated. Treating it as code — versioned in Git, reviewed in PRs, generated from authoritative sources — is the only way to keep it synchronized with the system's reality.
References
- Docs as Code — Write the Docs.
- MkDocs — MkDocs, 2024. Documentation site generator from Markdown.
- Docusaurus — Meta, 2024. Documentation framework with versioning and i18n.
Related content
- Spec-Driven Development
Development methodology where the specification is written before the code, serving as a contract between teams and as the source of truth for implementation.
- llms.txt
Proposed standard for publishing a Markdown file at a website's root that enables language models to efficiently understand and use the site's content at inference time.
- DraftMK Copier Templates
Copier templates for project scaffolding with Docker Compose, MkDocs documentation, and automated configuration.
- Developer Onboarding
Structured process for new developers to become productive quickly, from environment setup to understanding team architecture and processes.