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.
seed#documentation#docs-as-code#markdown#automation#dx
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.