Docs as Code

Docs as code is the practice of treating documents with the same engineering machinery as software: stored in version control as plain text (almost always markdown), changed through reviewable diffs, validated by automated checks, and published through a gated pipeline rather than saved into a wiki where quality goes to drift. The practice emerged from technical-writing teams at companies like Google and Spotify in the 2010s; the agentic era has turned it from a documentation philosophy into an operational necessity.

Why Agents Raised the Stakes

Two things changed. First, documents became load-bearing for behavior: a CLAUDE.md or SKILL.md isn't read by a human who applies judgment — it's executed, more or less literally, by every agent session that loads it. An error in these files compounds the way a code bug does. Second, agents became prolific writers of documents: PRDs drafted by agents, release notes generated from commits, specs revised by AI from review feedback. Volume without review machinery is how organizations drown in confident, unverified prose.

The Emerging Stack: CI for Prose

The mature form of docs-as-code mirrors the software pipeline component by component:

• Review with anchored threads — comments attached to the exact sentence at issue, with discussion, resolution, and an audit trail. The prose equivalent of PR review, minus the diff-hunk anchoring that breaks on documents.
• Review states — approve / request changes / comment, so a document's readiness is a fact, not a vibe.
• Checks — deterministic lint rules for prose: required sections present, banned placeholder text (TBD, TODO) absent, terminology spelled consistently, structure within bounds. Run on every revision, rendered pass/fail.
• Policies — named check-sets applied across a document class (“every PRD gets the PRD policy”), so standards are managed centrally rather than re-declared per file.
• Gates — publication (or the push back to the repo) blocked while reviews or checks are failing, with explicit human override.
• Agent reviewers — AI review of every revision: anchored suggestions with rationales, an honest review state, arriving within minutes of a save. Humans keep the accept and publish keys.

markupmarkdown implements this entire stack for markdown files — threaded review, states, one-click suggested edits, named check policies with index-wide pattern mapping, push gates, and server-fulfilled auto-review — with the file in the GitHub repo remaining the single source of truth throughout. It's the reference implementation of the argument this page makes: prose that steers agents deserves the same quality machinery as the code the agents write.

Where It's Headed

The direction of travel is toward symmetry: agents reviewing human documents, humans reviewing agent documents, and the same checks binding both. As documents become executable context — read by fleets of agents rather than occasional humans — the distinction between documentation quality and system quality dissolves. The teams treating their markdown with engineering discipline today are the ones whose agents behave tomorrow.