RFC: ADR-004 — Tabula rasa documentation standard (zero-context self-sufficiency)

[scottschreckengaust]

Summary

Establish a documentation standard where every guide, README, and decision record is written for a tabula rasa reader — someone with zero prior context about this project, its stack, or its terminology. Documentation must be self-contained, self-sufficient, and minimally sufficient: complete enough to operate end-to-end without external assistance, concise enough that experts aren't slowed by verbosity.

Use case and motivation

Who it's for: All contributors writing documentation, and all consumers reading it — from first-day engineers to senior architects, from human operators to autonomous agents with fresh context windows.

Problem today:

1. Tacit knowledge leaks — Authors assume readers know the stack, acronyms, AWS service names, or project history. A sentence like "bootstrap the CDK toolkit" means nothing to someone who hasn't used CDK before.
2. Context dependency — Guides reference other guides without indicating what the reader needs from them. The dependency graph is implicit.
3. Expert-only writing — Instructions skip "obvious" steps that are only obvious if you've done them before. A missing cd command or unexplained prerequisite breaks the entire flow for a new user.
4. Verbosity for experts — Conversely, some sections over-explain concepts that experienced users already know, making the guide feel bloated.
5. Agent context loss — AI agents start each session with no memory of prior interactions. Documentation that relies on "you saw this in the last section" or "as discussed earlier" fails for agents that compact or lose earlier context.

After this ADR:

• A brand-new user can follow any guide from start to finish without asking for help
• An expert can skim quickly by following the progressive disclosure structure
• An agent can execute any documented workflow without human clarification
• Documentation is testable — you can verify it works by running it cold

Proposed principles

1. The Tabula Rasa Test

Every document must pass this test: Can someone with zero project knowledge, following only what's written, complete the described outcome? If any step requires knowledge not present in the document or explicitly linked, the document fails.

How to apply:

• Before publishing, mentally simulate a reader who knows only general programming (not this project, not AWS, not CDK specifically)
• Every command must include: what directory to run it from, what environment variables are needed, what success looks like
• Every acronym must be expanded on first use with a one-line explanation

2. Minimally sufficient

Write the minimum that makes the reader succeed. Not the minimum possible words — the minimum sufficient content.

Audience need	How to serve it
Novice needs explanation	Provide a one-sentence "what this does" before each step
Expert needs speed	Use scannable structure (numbered steps, headers, tables) they can skim
Both need confidence	Show expected output or success criteria after key steps

3. Progressive disclosure (layered depth)

Structure every document in layers:

Layer 1: What (one paragraph — what this document helps you do)
Layer 2: Steps (numbered, self-contained, runnable)
Layer 3: Further reading (links to detailed explanations for those who want depth)

• Never force a novice to read expert material to proceed
• Never force an expert to wade through novice explanations to find the command
• Deep explanations go in "Further reading" links, not inline

4. International English

Write for non-native English speakers:

• Simple sentence structure (subject-verb-object)
• Avoid idioms, colloquialisms, and cultural references
• Prefer concrete words over abstract ones ("run this command" not "execute the following")
• One idea per sentence
• Active voice ("Run mise run build" not "The build should be run")

5. Self-contained references

When referencing another document:

• State what the reader will get from it: "See Deployment Guide for AWS account setup (required before this step)"
• Never assume the reader has read it: "If you completed the Deployment Guide, you already have X. If not, run: command"
• Never use "as mentioned above" or "as discussed in..." — each section must stand alone after context compaction

6. Testable documentation

Documentation is code. It should be verifiable:

• Commands must be copy-pasteable (no hidden dependencies)
• Expected output should be shown (or described) after non-trivial commands
• Prerequisites are listed explicitly at the top, not discovered mid-flow
• Error states are documented: "If you see X, it means Y. Fix: Z"

7. Terminology consistency

• Define a project glossary (terms, acronyms, service names)
• Use the same term everywhere for the same concept (don't alternate between "task," "job," and "work item")
• When introducing a project-specific term, bold it on first use with a parenthetical definition

Application to this repository

Document type	How this standard applies
docs/guides/ (Quick Start, Deployment, User)	Full tabula rasa compliance — these are the entry points
docs/design/ (Architecture, Orchestrator)	Layer 1-2 for orientation; technical depth is appropriate but prerequisites must be stated
docs/decisions/ (ADRs)	Context section must explain the problem without assumed knowledge; Decision section can be technical
AGENTS.md	Agent-facing; must be parseable without human clarification
README.md	First thing anyone reads; 30-second orientation must work for any reader
Code comments	Only the "why"; the "what" is in the code itself

Quality checklist (per document)

• First paragraph answers: "What does this document help me do?"
• Prerequisites listed at top (tools, accounts, prior steps)
• Every command includes the directory context (cd X or "from repo root")
• Acronyms expanded on first use
• No dangling references ("as discussed..." without a link)
• Expected output shown after non-trivial commands
• Error states documented for common failure modes
• Further reading links have one-sentence descriptions of what's there
• Passes the tabula rasa test (mentally simulate a cold reader)

Out of scope

• Rewriting all existing documentation (this ADR sets the standard; existing docs are improved incrementally)
• Automated readability scoring (future tooling, not governance)
• Translation to other languages
• Video or interactive tutorials

Alignment

This RFC aligns with the roadmap's Documentation and specifications theme:

"Publish and surface human- and machine-readable specs... so operators and contributors can modify, extend, or fork the solution without reverse-engineering the codebase."

Self-sufficient documentation is the foundation for this goal.

Dependencies

• docs/decisions/ framework (ADR-001, PR docs: establish ADR framework and ADR-001 stacked pull requests #130)
• Benefits from ADR-003 (RFC: ADR-003 — Contribution governance for async agents and humans #134) governance process for iterative improvement

Alternative solutions

Approach	Why not preferred
"Just write better docs" (no standard)	Subjective; each author has different assumptions about reader knowledge
Comprehensive verbose docs	Experts bounce; maintenance burden grows; content rots faster
Wiki with community edits	Loses version control; quality varies; not agent-accessible
Generated docs only (from code)	Misses the "why" and workflow context; API docs ≠ user guides
Separate docs per audience (novice/expert)	Maintenance doubles; information drifts between versions

Open questions

1. Should there be a formal "documentation review" step in the PR process (like code review but for docs)?
2. Should the glossary live in its own file or be embedded in AGENTS.md?
3. How do we measure documentation quality over time? (user feedback? agent success rate on cold starts?)
4. Should we add a CI check for common readability issues (unexpanded acronyms, missing prerequisites sections)?

Self-improvement note

This standard applies to itself. An agent reading this ADR for the first time — with no knowledge of the project — should understand what problem it solves, what rules it establishes, and how to apply them. If any part of this document requires external context to understand, it has violated its own principle.

Agents operating under ADR-003 governance should flag documentation PRs that violate these principles during pre-start cross-reference audits.

---

Note: This RFC follows ADR-003 (#134) governance rules. Once approved by an admin, an assigned contributor should implement as ADR-004.

• RFC PR: (pending approval)
• Approved by: (pending)
• Reviewed by: (pending)