Documentation practices

Documentation Practices

Purpose

Wrong documentation is worse than none: it is trusted, followed, and only discovered false at the worst moment. This skill is the discipline for docs that stay true — the README as an executable contract, each document knowing which of four jobs it does, rationale stored where readers decide, volatile claims date-stamped with re-verification commands, and the courage to delete what has gone false.

Metadata

• Prerequisites: none (loadable standalone).
• Related Skills: system-design (owns ADR content; this skill keeps ADRs true over time), configuration-management (owns .env.example semantics; this skill owns it as a documentation contract), codebase-onboarding (the primary consumer of good docs), research-methodology (date-stamping and epistemic labels originate there), api-and-interface-design (interface reference docs).
• Owns: documentation types and their selection; README-as-contract; doc drift management; what-NOT-to-document; documentation for AI-agent readers.

When to Use / When NOT to Use

Use when:

• Writing or revising any README, guide, docstring, threat model, or .env.example.
• A doc and the code disagree (drift incident — this skill owns the response).
• Deciding whether something needs documenting at all.
• Preparing a repo for new contributors or AI agents.

Do NOT use (load the sibling instead):

• Authoring the content of a design decision → system-design (ADR format); this skill governs its lifecycle.
• The "documentation" is an interface's error/usage contract → api-and-interface-design.
• Investigating what is TRUE before writing it down → research-methodology.
• Writing code comments inside a diff → keep them to constraints the code can't show (change-control's comment rule); comments are code, not docs.

Definitions & Mental Model

The four documentation types (each answers a different reader's question — mixing them produces documents that serve no one):

• Tutorial — "teach me by doing": a guided, guaranteed-to-work first experience. Optimized for confidence, not completeness.
• How-to — "help me accomplish X": task-shaped steps for a reader who knows what they want.
• Reference — "tell me the facts": exhaustive, structured, lookup-shaped (API surfaces, config variables, flags).
• Explanation — "help me understand why": rationale, tradeoffs, threat models, architecture reasoning.

Further terms:

• Executable contract: documentation whose claims can be run — install/test/run commands a stranger pastes verbatim. In a repo without CI, the README is the CI: its commands are the only stated verification.
• Drift: the gap that grows between docs and reality. Not preventable — only manageable, via date-stamps, re-verification commands, and deletion.
• Docs-near-code: rationale placed at the point of decision — the constraint comment at the scar site, the threat model in the README, the docstring on the public surface — because distance from the code is proportional to drift speed.

Mental model: documentation is a cache of the truth, and caches go stale. A principal engineer therefore treats every doc like cached data: write it close to its source (docs-near-code), stamp it with when it was cached (dates), attach the cache-refresh command (re-verification), and evict aggressively when invalidated (delete wrong docs — a 404 is honest; a stale page lies). The corollary is ruthless economy: every sentence you don't write is a sentence that can't go stale, so document only what the code cannot say.

Core Methodology

1. Pick the document's single type before writing (decision tree):

What is the reader's question?
├─ "How do I get this running for the first time?"
│    → TUTORIAL. One golden path, every command verified, no options.
├─ "How do I do <specific task>?"
│    → HOW-TO. Numbered steps, prerequisites stated, one task per doc.
├─ "What are all the <flags/vars/endpoints/fields>?"
│    → REFERENCE. Complete, structured, no narrative. Generated from
│      source where possible (--help output, schema) so it can't drift.
└─ "Why is it like this?"
     → EXPLANATION. Rationale, rejected alternatives, threat model.
       (Decision records specifically: system-design's ADR format.)
Mixed question → two documents, cross-linked. Never one hybrid.

2. Make the README an executable contract. Its required spine, in order: one-sentence purpose → prerequisites (including non-package ones a build file can't express: model downloads, system services, accounts) → install command → run command → test command → the pointer map (where config/docs/deeper material lives). Every command must be one a stranger pastes verbatim into a fresh clone — no "adjust as needed", no tribal placeholders. Test it that way before committing. In a zero-CI repo, state it plainly to yourself: these commands are the project's only verification contract, so breaking them is breaking the build.
3. Put rationale where the reader decides. The explanation belongs at the decision point:
   • Constraint/rationale that saves a future editor from re-breaking something → in-code comment at the scar site (e.g. next to the safety flag it justifies).
   • Trust assumptions → threat model in the README or SECURITY.md, where a user decides whether to run the thing (security-review-playbook step 1 produces it; this skill houses it).
   • Setup facts config can't express → README prerequisites.
   • Why-this-pin → the commit message and/or a manifest comment (dependency-management step 4).
   • Decisions with alternatives → ADR (system-design step 8).
4. Maintain .env.example as the setup contract. Every variable NAME the code reads, a placeholder value, a one-line comment (purpose, required scope, default). It must stay one-to-one with what the config module reads — a variable in code but not in the example is an undocumented coupling (semantics owned by configuration-management; the contract discipline lives here).
5. Manage drift deliberately:
   • Date-stamp volatile claims — versions, counts, URLs, "currently supports" — as "(as of YYYY-MM-DD)" (research-methodology step 6).
   • Attach re-verification commands to repo-specific claims: the exact command that re-checks the fact.
   • Update docs in the same change that invalidates them — a PR that changes a command updates every doc quoting it (grep for the old command; it is part of the caller-enumeration discipline in change-control).
   • Delete wrong docs on discovery. Found-false documentation is removed or fixed immediately, never left "to fix later" — a reader between now and later will follow it off the cliff.
6. Apply the what-NOT-to-document filter. Do not document:
   • What the code says clearly (a docstring restating the signature; a comment narrating the next line).
   • Generated artifacts and their internals (document the generator's invocation instead).
   • Speculative futures ("eventually this will...") — roadmaps rot fastest; keep them out of technical docs.
   • Per-file changelogs (git history owns change narration). Every deleted candidate sentence is drift that can never happen (engineering-minimalism applied to prose).
7. Write for AI-agent readers too. Increasingly the "stranger with a fresh clone" is an agent. The same practices serve both, sharpened: exact commands over prose descriptions of commands; explicit paths over "the usual place"; stated preconditions over assumed context; no tribal shorthand or unexpanded acronyms on first use. A doc an agent can execute is a doc a tired human can execute.
8. Audit docs on a cadence and after incidents. Quarterly (or per release): run every README command in a fresh clone; run the re-verification commands; re-stamp or delete. After any incident where a doc misled: fix the doc in the incident's own change.

Documentation review checklist

• Document has exactly one type, matched to one reader question
• README spine complete; every command paste-verified in a fresh clone
• Non-package prerequisites (services, models, accounts) stated in the README
• Rationale placed at the decision point (scar-site comment / README threat model / ADR)
• .env.example one-to-one with the variables the code reads
• Volatile claims date-stamped; repo-specific claims carry re-verification commands
• The change that invalidates a doc updates that doc, same diff
• Nothing documented that the code already says; no speculative futures
• No tribal shorthand; commands and paths explicit enough for an agent
• Known-false docs deleted, not deferred

Discovery & Audit Commands

# Inventory the documentation surface
find . -iname "*.md" -not -path "*/node_modules/*" -not -path "*/.git/*" | head -20
ls README* CONTRIBUTING* SECURITY* .env.example docs/ 2>/dev/null

# Does the README's contract hold? (extract and eyeball its commands)
grep -n '```' -A 3 README.md | grep -vE '^\s*```' | head -30

# .env.example vs what the code actually reads (the two lists must match)
grep -oE "[A-Z][A-Z0-9_]{2,}" .env.example 2>/dev/null | sort -u
grep -rhoE "getenv\(['\"][A-Z0-9_]+|environ\[['\"][A-Z0-9_]+" --include="*.py" . | grep -oE "[A-Z][A-Z0-9_]+" | sort -u

# Drift hunt: commands quoted in docs that no longer exist in the build config
grep -rn "npm run\|pip install\|pytest\|cargo" --include="*.md" . | grep -v node_modules | head -20
# ...then compare against: grep -A 20 '"scripts"' package.json  /  pyproject.toml

# Stale-claim hunt: undated volatile statements
grep -rn -iE "currently|at the moment|latest version|for now" --include="*.md" . | grep -v node_modules | head

# Doc-to-code distance: rationale far from its decision point
grep -rn -iE "threat model|security boundary" --include="*.md" . | grep -v node_modules

Failure Modes & Anti-patterns

Symptom	Mistake	Correction
New contributor blocked in the first ten minutes	README commands never paste-tested	Fresh-clone verification of every command (step 2)
Setup fails on a step no doc mentions	Non-package prerequisite undocumented	Prerequisites section carries what build files can't express (step 2)
One giant README doing four jobs badly	Types mixed in one document	One type per doc; cross-link (step 1)
"Why is this flag here?" answered by archaeology	Rationale far from the decision	Scar-site comment / README threat model / ADR (step 3)
App won't boot; the missing env var isn't in the example	.env.example drifted from the config module	One-to-one audit; update in the same change as config edits (step 4)
Doc says X, code does Y, both survive for months	Wrong doc left "to fix later"	Delete or fix on discovery, in that change (step 5)
"Supports versions 3.9–3.11" — false for a year	Volatile claim undated, unverifiable	Date-stamp + re-verification command (step 5)
Docstring restates the function signature	Documenting what the code says	The not-document filter; delete it (step 6)
Roadmap section describing features that never came	Speculative futures in technical docs	Keep aspiration out; document what is (step 6)
Agent (or intern) can't execute the "obvious" step	Tribal shorthand and implied context	Exact commands, explicit paths, stated preconditions (step 7)

Worked Example

Task: a small service's docs consist of one stale README; new contributors keep failing setup.

1. Type triage: the README is a hybrid (history + setup + API dump + musings). Split: README (tutorial spine only), docs/api.md (reference, generated from the OpenAPI file so it cannot drift independently), docs/why-queue.md (explanation of the one contested design choice, as a dated ADR).
2. Contract rebuild: fresh clone on a clean machine; follow the README verbatim. It fails twice — a missing system dependency (the message broker) and an undocumented SERVICE_SECRET. The README gains a Prerequisites line for the broker; .env.example gains SERVICE_SECRET= # HMAC secret for callbacks; generate with: openssl rand -hex 32. Re-run: green.
3. Drift controls: the supported-runtime claim becomes "Python 3.11–3.13 (as of the last verification date; see checklist below)"; a five-line "Doc verification" checklist lands at the README's foot: fresh-clone the repo, run install/test/run, diff .env.example against the config module.
4. Deletions: the "future plans" section (three years stale) is deleted; the per-file CHANGELOG (abandoned at v0.2) is deleted in favor of git history. Net diff: −180 lines of prose, and setup failures stop.

Repository Examples

Repo facts below are point-in-time illustrations (as of 2026-07-04) — examples, never assumptions about your system.

• agentix (~/agentix) — rationale at the decision point, twice: the README carries the threat model verbatim ("the security boundary is you and the model you point it at, not the code") exactly where a user decides whether to run it, and the in-code comment sits at the scar site — np.load(..., allow_pickle=False) annotated "a tampered DB blob must not be able to execute code on load". The README also documents the non-package prerequisites build files can't express: ollama pull llama3.2 and ollama pull nomic-embed-text. The shell blocklist is documented honestly as a guardrail with its bypass named — documentation that refuses to over-claim.
• prism (~/prism) — the executable contract maintained: .env.example documents every variable with defaults (GITHUB_TOKEN, GITHUB_WEBHOOK_SECRET, OLLAMA_HOST, OLLAMA_MODEL, MAX_FILES_PER_PR, MAX_LINES_PER_CHUNK), and commit b7bbabb "Update README with env var reference" is the same-change doc-sync discipline in the history. Zero CI means the README's pip install -e . / pytest tests/ ARE the verification contract.
• ragit (~/ragit) — constraint plus reason, together: the README documents Python 3.10–3.13 support WITH the why ("some vector DB dependencies may not publish wheels for very new Python versions yet"), and the pin commits (a1ad63ed, 0a06ae9b) carry their rationale in the messages — documentation-in-history.
• ruflo (~/ruflo) — the limit of documentation: the repo's CLAUDE.md documents the three-package publish process and marks the ruflo dist-tag "EASY TO FORGET" — yet the slip still happened once (commit "fix: ...dist-tags, bump to alpha.3"). A written checklist is a guardrail, not a boundary; when a documented step keeps failing, the next move is mechanization, not bolder fonts.

Validation Criteria

You applied this skill correctly when:

1. A stranger (or an agent) completes the README's install→run→test spine in a fresh clone without asking anything.
2. Every document answers exactly one of the four reader questions, and you can name which.
3. The .env.example audit (two sorted lists) shows a one-to-one match with the code.
4. Volatile claims carry dates; repo-specific claims carry runnable re-verification commands.
5. git log shows docs updated in the same changes that invalidated them.
6. The docs got shorter wherever the code already spoke — deletions are visible in the history.

Provenance & Maintenance

• Sources: ~/agentix, ~/prism, ~/ragit, ~/ruflo — investigated 2026-07-04. The four-type taxonomy is the industry-standard documentation framework (widely known as Diátaxis). Skill authored 2026-07-06.
• Assumptions: repo doc facts are point-in-time; the ruflo CLAUDE.md publish-process text is quoted from the 2026-07-04 investigation.
• Re-verification commands:

  grep -in "boundary\|ollama pull" ~/agentix/README.md | head
  cat ~/prism/.env.example
  grep -in "3.10\|wheels" ~/ragit/README.md | head
  grep -n "EASY TO FORGET" ~/ruflo/CLAUDE.md
  

• Likely to drift: every quoted README/example fact (that is this skill's own subject matter — eat the dog food: re-stamp on audit); the .env.example variable lists.
• Maintenance checklist:
  • Re-run re-verification; re-stamp Repository Examples.
  • Fresh-clone-test this library's own LIBRARY.md claims while auditing.
  • Confirm cross-referenced skills still exist under their directory names.