Minimum Viable Documentation¶
Documentation scoping — instantiates Minimum Sufficient Solution
Writes only the documentation a real operator needs to act, maintain, hand off, and escalate — and proves it by having a fresh reader complete the task.
Minimum Viable Documentation scopes the writing to what a real reader must know to act correctly — no more, and crucially no less. Its defining move is that sufficiency is defined by the reader's task, not the author's completeness: the question is never "have we documented everything?" but "can the person who will actually use this get the job done, maintain the thing, hand it off, and know when to escalate?" That reframing does two things at once. It licenses cutting the reference-manual bulk that no one reads, and it forbids cutting the small set of things whose absence causes harm — the safety warning, the rollback step, the escalation contact. This is not a refusal to document; it is documentation sized to use and validated against a live reader.
Example¶
An engineering team owns an internal payments service and is writing the on-call runbook. The maximalist draft is a sixty-page wiki covering the full architecture, every config flag, and the history of the schema. Minimum Viable Documentation asks instead who reads this and to do what: an on-call engineer, at 3am, trying to stop a failing deploy and restore payments. The scoped runbook is four pages — how to tell the service is unhealthy, the exact rollback command, how to confirm recovery, and who to page if rollback does not work — written for that reader and that task. The invariants that stay in regardless of length are the ones whose absence would cause real damage: the "do not truncate the ledger table" warning, the data-handling note for a regulated field, and the escalation tree. Then the real test: a teammate who has never touched the service is handed only the runbook and asked to walk the recovery. Where they stall is where the docs are actually insufficient — and that, not the author's sense of thoroughness, sets what gets added back.
How it works¶
- Name the reader and the task. Scope to a specific audience doing a specific job — on-call recovery, first-day onboarding, safe handoff — rather than to the subject in the abstract.
- Cut to what the task needs. Remove the reference bulk that serves completeness rather than action, keeping the doc short enough that it is actually read under pressure.
- Pin the harm-preventing content. The warnings, safety steps, and escalation paths whose absence causes damage stay in no matter how lean the rest becomes.
- Validate on a fresh reader. Hand the draft to someone who does not already know the answer and watch where they stall; their failures, not the author's judgment, mark the gaps.
Tuning parameters¶
- Audience narrowness — how tightly the doc targets one reader-and-task. Narrow docs are usable and fast but multiply into many small pages; broad docs consolidate but drift toward the unread manual.
- Assumed reader expertise — how much prior knowledge the writing takes for granted. Assuming more shortens the doc but strands the true novice it was meant to serve.
- Update coupling — how tightly the doc is tied to the thing it describes, from hand-maintained to generated-from-source. Tighter coupling keeps it honest but constrains how it can be written.
- Validation rigor — whether the fresh-reader walkthrough is a casual read or a monitored task run. More rigor finds more gaps but costs a real person's time.
When it helps, and when it misleads¶
Its strength is that documentation scoped to a task and tested on a stranger is documentation people actually use — short enough to read at 3am, and honest about where it fails. Its failure mode is the curse of knowledge: an expert author cannot un-know the context and so writes docs that are perfectly clear to themselves and useless to the newcomer, silently assuming the very steps the reader is missing.[1] The classic misuse is invoking "minimum viable" to skip the harm-preventing content — cutting the safety warning or escalation path because it made the page longer. The guarding discipline is to keep the invariant content non-negotiable and to let a genuine outsider, not the author, be the judge of sufficiency.
How it implements the components¶
preserved_invariant_set— the harm-preventing content (safety warnings, rollback steps, escalation paths, regulated-data notes) is pinned as uncuttable no matter how lean the rest becomes.sufficiency_test— a fresh reader is handed only the docs and asked to complete the task; where they stall defines what is genuinely insufficient.stakeholder_need_trace— the doc is scoped to a named reader and the specific job they must do, so every section traces to an actual use.
It documents a solution but does not decide its scope: the core_requirement and the graded nonessential_feature_filter are set upstream by MVP-like Scoping and Must/Should/Could Filter, and the deferred_enhancement_backlog of parked capabilities is Essential Feature Set's artifact. Its fresh-reader check tests the writing; a live bounded run of the whole solution is Pilotable Solution's.
Related¶
- Instantiates: Minimum Sufficient Solution — minimum viable documentation is the archetype applied to the written record, where "sufficient" means a real reader can act.
- Sibling mechanisms: Essential Feature Set · Must/Should/Could Filter · Lean Policy Design · MVP-like Scoping · Pilotable Solution · Simple Intervention Package · Minimum Viable Process
Editorial Notes¶
Form Classification¶
Form family: Representation, Specification & Plan
Rationale: Minimum Viable Documentation operates as a non-executable information artifact that externalizes static or prospective structure because it writes only the documentation a real operator needs to act, maintain, hand off, and escalate — and proves it by having a fresh reader complete the task.
Independent corroboration: The frozen evidence defines Minimum Viable Documentation as 'Writes only the documentation a real operator needs to act, maintain, hand off, and escalate — and proves it by having a fresh reader complete the task', so its operative form is Representation, Specification & Plan.
Nearest alternative: Experiment, Test & Rehearsal — Fresh-reader testing validates the draft, but the mechanism's deployable form is the scoped operator-facing documentation artifact.
Review outcome: Independent reviewer agreement; medium confidence.
Origin Attribution¶
Primary origin: Computer Science & Software Engineering
Origin pattern: Cross-disciplinary synthesis
Present-day reach: Multi-domain
Rationale: Task-tested minimal documentation arises in agile software and technical-documentation practice.
Related originating lineages:
- Engineering & Design — Operating and maintenance documentation supplies safety-critical completeness criteria.
- Organizational & Management Science — Knowledge transfer and handoff requirements shape minimum organizational sufficiency.
Review resolution: Both independent reviews place the primary provenance in computer_science. The queued differences (alternate_origin_disagreement, encyclopedia_synthesis_disagreement) concern secondary metadata, not primary lineage. The final retains engineering_design, organizational_management only where a reviewer supplied a formative-lineage rationale; downstream use or broad applicability by itself is not treated as origin. origin_mode=cross_disciplinary_synthesis because the supplied rationales identify formative contributions that are composed in the mechanism's present form. domain_reach=multi_domain records established application breadth separately from provenance. confidence=medium preserves the more cautious evidence assessment. encyclopedia_synthesis=true records whether either reviewer identified deliberate corpus-level composition.
Encyclopedia synthesis: The exact catalogued form synthesizes established practice rather than reproducing a single standard historical label.
Review outcome: Reconciled after independent review; medium confidence.
References¶
[1] Camerer, Colin F., George Loewenstein, and Martin Weber. "The Curse of Knowledge in Economic Settings: An Experimental Analysis". Journal of Political Economy 97(5), 1232–1254 (1989). Shows that better-informed people cannot fully ignore private knowledge when estimating less-informed judgments. registry ↩