The Problem: Documentation Drift
In the past, documentation lived in Word documents, Confluence pages, or internal wikis disconnected from the codebase. This created a predictable failure mode called documentation drift: the code evolves through dozens of pull requests, but the docs are never updated. Within months, the documentation actively misleads readers — which is worse than no documentation at all.
The root cause is structural: when docs live in a separate system from code, updating them requires a separate, manual, context-switching effort. Engineers skip it under deadline pressure, and nobody enforces it.
The Solution: Docs as Code
Docs as Code is the philosophy that documentation should be managed with the same tools, workflows, and discipline as software source code:
- Source Control: Documentation lives in Git repositories, typically in a
docs/directory alongside the code it describes. Every change is tracked, attributed, and reversible. - Plain Text Formats: Docs are written in human-readable markup languages — primarily Markdown (
.md) or AsciiDoc (.adoc) — not proprietary binary formats like.docx. Plain text diffs cleanly in Git. - Pull Request Review: Changes to documentation go through the same PR process as code changes. Reviewers check for technical accuracy, clarity, and completeness.
- Automated Testing (Linting): CI pipelines run documentation linters to catch errors automatically before merge.
Common Documentation Linters
| Tool | What It Checks |
|---|---|
markdownlint |
Markdown formatting rules (heading levels, list style, line length) |
proselint |
English prose quality (passive voice, clichés, redundancy) |
vale |
Configurable style guide enforcement (e.g., enforce your company's style guide) |
link-checker |
Detects broken hyperlinks in documentation |
A typical CI workflow runs on every pull request: check out the repo, run markdownlint against every file under docs/, then run vale for prose-quality checks — any failure blocks the merge.
The Workflow in Practice
When a developer changes a feature, they see the docs/ directory right next to the src/ directory in the same repository. The PR template can include a checklist item: "Did you update the relevant documentation?" Reviewers can reject a PR that changes behavior without updating docs. This structural proximity is what makes Docs as Code effective — it removes the friction of switching contexts.
Key insight for senior engineers: Docs as Code is not just a tooling choice; it is a cultural statement that documentation is a first-class engineering artifact. Teams that adopt it signal that shipping undocumented features is equivalent to shipping untested code — both are incomplete.