Documentation as Code
debt(d9/e5/b7/t5)
Closest to 'silent in production until users hit it' (d9). The detection_hints note automated=no, and the listed tools (mkdocs, docusaurus, hugo, adrs) are doc-generation tools, not detectors of drift. Documentation diverging from code is invisible — there is no compiler or linter that flags a stale README or missing ADR. The gap only surfaces when an engineer follows outdated guidance, during an incident when a runbook is missing, or in an onboarding failure.
Closest to 'touches multiple files / significant refactor in one component' (e5). The quick_fix requires migrating docs from an external wiki into the repo, creating ADRs in docs/adr/, adding runbooks in docs/runbooks/, wiring OpenAPI annotations for API docs, and establishing a PR review convention for docs. This is not a single-line patch; it involves multiple files, directory structure decisions, and a team process change, but doesn't require rearchitecting the code itself.
Closest to 'strong gravitational pull' (b7). The choice of where documentation lives (repo vs. external wiki) shapes every future PR workflow, every incident response, every onboarding path, and every architectural decision record process. The applies_to covers both web and cli contexts, meaning it affects all contributors across the codebase continuously. Once the pattern is established (or anti-pattern entrenched), every new doc, runbook, and ADR is pulled toward the existing convention.
Closest to 'notable trap (a documented gotcha most devs eventually learn)' (t5). The misconception is explicit: developers assume a wiki is sufficient and equivalent to docs-as-code. This is a common and widely documented pitfall — wikis feel like a reasonable solution until the inevitable drift becomes painful. It's a trap most teams learn after experiencing stale documentation in an incident or during onboarding, making it a t5 rather than a catastrophic or obscure surprise.
Also Known As
TL;DR
Explanation
Documentation as Code (Docs-as-Code) means writing docs in plain text formats (Markdown, AsciiDoc, reStructuredText), storing them in the same repository as the code, reviewing them in pull requests, and generating publishable sites via CI (MkDocs, Docusaurus, Sphinx). Benefits: docs are versioned with the code they describe, changes require review, and docs never drift to a separate wiki that falls out of date. OpenAPI specs generated from code are an example of docs-as-code taken to its logical conclusion.
Common Misconception
Why It Matters
Common Mistakes
- Documentation in a separate wiki — never reviewed with code changes, guaranteed to drift.
- README that only covers installation but not architecture decisions or common workflows.
- Not including runbooks alongside the code that requires them — ops team cannot find them in an incident.
- Documentation written once and never maintained — schedule periodic doc reviews as part of sprint planning.
Code Examples
# Docs in Confluence — disconnected from code:
# PR: 'Refactor payment gateway to use Stripe v3'
# No documentation update required in PR
# Confluence page: still describes Stripe v2 API
# New developer follows outdated docs
# 2 hours debugging why the old endpoints dont work# Docs in repo — reviewed with code:
# PR: 'Refactor payment gateway to use Stripe v3'
# Required: update docs/payments.md alongside code changes
# CI check: markdownlint, link checker
# Reviewer sees doc changes alongside code changes
# docs/adr/0012-stripe-v3-migration.md explains the why
# New developer reads accurate, current documentation