Skip to content

D.O.C.S. documentation

Discover audience · Organize by task · Clarify with examples · Sustain through ownership

D.O.C.S. is the documentation discipline for AI-assisted codebases. It exists because AI tools have changed the economics of documentation in two directions simultaneously:

  • Easier to produce. Boilerplate, API references, glossary entries, and example snippets are cheap to draft.
  • Easier to rot. AI-generated docs without a named owner decay faster than hand-written ones, because nobody felt the cost of writing them and so nobody feels the cost of maintaining them.

The discipline is the same as it was before AI assistance (audience, task, examples, ownership), but the threshold for when AI helps versus when AI hurts has shifted.

When AI helps and when AI hurts

AI is a help for… AI is a hazard for…
Boilerplate (parameter tables, type signatures, getting-started snippets) Architectural decisions and the why behind them
Glossary entries and definitions Runbooks and incident playbooks
Worked examples for documented APIs Post-mortems and root-cause analyses
Translation and localization of stable content First drafts of design proposals
Style consistency passes on existing prose Anything that requires lived team context
Diagram captions, alt text, summaries Anything where being subtly wrong is dangerous

The pattern: AI helps where there is a verifiable source of truth in the code or the existing docs, and hurts where the truth lives in people's heads or in operational reality.

A runbook generated by a model that has never seen the system in production is plausible-shaped fiction. A glossary entry generated by a model that read the existing glossary is a draft a human can polish.

The four parts

D. Discover audience

Before drafting, name the audience:

  • Internal new joiner in their first week?
  • External developer integrating against an API?
  • On-call engineer at 3 a.m. with a paging alert?
  • Auditor verifying a compliance control?
  • Future maintainer in 18 months, with no current-team context?

The audience determines tone, depth, and what is taken for granted. Documentation that tries to serve all five audiences in one page serves none of them. AI tools default to a "general developer" tone that serves the first audience well and the others poorly.

For each artifact, name one primary audience and at most one secondary. Write for the primary; cross-link for the secondary.

O. Organize by task

Group documentation around what the reader is trying to do, not around the structure of the code:

  • Tutorials: teach a new user a small thing end-to-end.
  • How-to guides: accomplish a specific task.
  • Reference: look up a parameter, a config, an API.
  • Explanation / concepts: understand the why.

This is the Diátaxis framework1, and it predates AI assistance. AI assistance does not change the framework; it changes which quadrants are cheap to draft.

The most common AI-aided drafting failure is producing a "documentation page" that mixes all four quadrants: a tutorial that becomes a reference that becomes an explanation halfway through. Decide which quadrant the page is in, and stay there.

C. Clarify with examples

Examples are where AI is most reliably useful, if the examples are verified:

  • Each example must be runnable as written. Test it.
  • Each example must use realistic data, not foo and bar (which models default to).
  • Each example must reference actually existing APIs, libraries, and versions, not the model's plausible guess. (See V.E.R.I.F.Y. Fact-check sources.)
  • Each example must show failure modes, not only the happy path.

A worked example that fails to compile, or uses a function that does not exist, is worse than no example; it teaches the reader the wrong thing while signaling false confidence.

When the team has automated documentation testing (executable code blocks, doctests, snippet runners), AI-aided example drafting becomes much safer. When it does not, treat AI-drafted examples as suspect until the author has run them.

S. Sustain through ownership

Every documentation page has:

  • A named owner. A person, not a team. Teams forget; people remember being asked.
  • A last_updated date: the date the content was last verified, not the date the file was last touched.
  • A review_by date: when the owner has agreed to look at it again.
  • A status: draft, current, deprecated, archived.

This is the same convention used in this framework's frontmatter (see the top of any page on this site). It is not bureaucratic ceremony; it is the only thing that prevents documentation rot.

AI-generated documentation rots fastest because nobody felt the cost of writing it. A page nobody owns is a page that will mislead the on-call engineer six months from now. If a generated page has no owner, the right move is not to soften that; it is to delete the page.

How D.O.C.S. composes with other practices

Trigger Documentation produced Owner
New feature merged Reference page + example Author of the change
Architectural decision Decision Record Decision sponsor
Incident closed Runbook update + post-mortem Incident commander
Refactor completed Updated module README + intent statement R.E.F.A.C.T. lead
New tool approved AUP / vendor standards update CISO or delegate
Quarterly review Status sweep on last_updated and review_by Documentation owner per area

A change is not "done" until its documentation has been updated. That is the standard the framework enforces. AI assistance does not relax it.

Sizing guidance

Sizing guide

  • Small (< 50). A single docs/ folder per repo, with frontmatter on every file. One person owns docs across all repos. Quarterly audit.
  • Mid (50–500). Per-team documentation owners; a central style guide; doc review as part of PR review for any change with user-visible behavior.
  • Enterprise (500+). Documentation as a program: named owners per domain, doc-CI (build, link-check, snippet tests), retirement workflow for deprecated pages, content metrics.
  • Regulated. Documentation feeds the audit trail. Decision Records are mandatory for Tier High/Critical changes; runbooks are versioned alongside the systems they cover.

What to never let AI write unsupervised

A short, hard list:

  • Architecture decisions. A model that has not been in the system for two years cannot reliably articulate why the system is the way it is. The model can propose a decision; a human writes the Decision Record.
  • Runbooks. A runbook that has not been tested against the actual system is a story, not a runbook. Generate a draft if you must, but every step must be verified end-to-end before publication.
  • Post-mortems and root-cause analyses. These document organizational learning. The model has none of the lived context.
  • Compliance attestations. A model can summarize what a control should do; it cannot attest that the control is in place. Compliance language must come from the responsible humans.
  • Security advisories about your own systems. The blast-radius judgments are organizational, not textual.

For all of these, AI assistance is fine for drafting boilerplate inside a human-authored frame, but the human owns the frame.

Anti-patterns

Don't

  • Don't publish AI-generated runbooks without verifying every step. A runbook the on-call engineer cannot follow under pressure is worse than no runbook.
  • Don't let AI write architecture documents. A model can describe an architecture; it cannot reason about why your architecture is the way it is. The result hallucinates the actual architecture in plausible-shaped prose.
  • Don't ship AI-generated pages without a named human owner. A page nobody owns is a page that will mislead someone six months from now and mislead nobody to fix it.
  • Don't use AI for post-mortems. The whole point of a post-mortem is to capture the learning the team experienced. The model wasn't there.
  • Don't accept "the docs have been updated" without checking the last_updated date. A doc updated last quarter is a doc that has been outdated for ninety days.

Next

  1. Diátaxis, "A systematic framework for technical documentation authoring", Daniele Procida. [primary, methodology] ↩