Docs as code

Docs as code

The reason docs go stale is that they live apart from the code they describe, changed by different people through a different process. Docs-as-code closes that gap: documentation lives in the repo, changes in the same pull request as the code, and CI checks it: so drift becomes a build failure instead of a discovery months later.

Method

1. Keep docs in the repo, beside the code. Markdown (or the docs framework's format) versioned with the source: the docs for a feature live next to it and change in the same commit. This co-location is the whole idea: the documentation and the code share one history, one review, one source of truth (see monolith-first's co-location instinct, applied to docs).
2. Change docs in the same PR as the code. A change that alters behavior updates the docs in the same pull request, reviewed together (see pull-request-size, code-review): the reviewer checks that the docs match the change while both are fresh. Separate docs-later tickets are how docs fall permanently behind.
3. Check docs in CI. Link checking (dead links fail the build), spell/style linting (see style-guides), and crucially, testing that code examples actually run (see api-reference-docs, tutorial-writing): a broken example fails CI like a broken test. Automated checks are what make "docs match reality" enforceable rather than aspirational.
4. Build previews on every change. A rendered preview of the docs per pull request (the framework deployed to a preview URL) lets reviewers see the actual output, not the raw markup: catches formatting breaks and reads the way users will. Reviewing docs as source is like reviewing a rendered UI as HTML.
5. Generate what should be generated, write what should be written. API reference from the schema (see api-reference-docs), CLI help from the parser, config options from the code: generated so they never drift; conceptual guides, tutorials, and rationale hand-written because no generator produces insight. Know which is which and wire the generation into the build.
6. Lower the contribution barrier. If fixing a typo requires learning a bespoke CMS, typos stay; if it is a markdown edit in the repo with a preview, anyone fixes it (see community-building's contributor ladder). The docs-as-code payoff includes that the whole team, not a docs silo, keeps docs current.

Boundaries

• Docs-as-code fits developer-facing and technical docs well; end-user documentation with heavy media, localization, and non-technical authors may need a CMS or hybrid: match the tooling to who writes and reads.
• The workflow's value depends on the CI checks being real (tested examples, link checks): docs-in-the-repo without the checks is just a different place for stale docs to live.
• Generated docs still need curation (see api-reference-docs); "generate everything" produces complete, correct, and unhelpful reference. The method is generate-plus-write, both in the repo.