Start from a verified need
Document a real user outcome. Do not use content to justify a product structure that already exists.
Research synthesis
Technical documentation is a production system.
Strong output begins with a verified user need. It separates reader intent, composes reusable modules, connects facts to technical truth, tests practical assertions, and measures whether the reader succeeds.
Six principles govern the system.
These principles constrain structure, presentation, workflow, and quality. They prevent polished output from becoming visually impressive but operationally weak.
One dominant intent
Tutorials teach. How-to guides enable work. Reference establishes truth. Explanation builds a model.
Structure before components
Model claims, evidence, decisions, sequences, and constraints before selecting cards, tabs, or diagrams.
Truth has provenance
Connect exact behavior to schemas, executable examples, subject-matter review, and observed evidence.
Every page is an entry point
Readers arrive through search, deep links, tickets, chat, and agents. Each page must orient independently.
Measure reader success
Page views are not outcomes. Track first success, task completion, recovery, retrieval, and comprehension.
Different methods solve different failure modes.
The strongest system combines complementary approaches. Use the filters to inspect the methodology by problem domain.
User-needs content design
Begin with evidence about who needs to achieve what, in which situation, and why current paths fail.
- Prevents irrelevant pages
- Creates content acceptance criteria
- Aligns scope to outcomes
Task analysis
Decompose real work into decisions, subtasks, dependencies, frequency, complexity, and failure points.
- Matches actual workflow
- Finds missing prerequisites
- Exposes recovery paths
Diátaxis
Separate tutorials, how-to guides, reference material, and explanations according to reader intent.
- Prevents mixed-purpose pages
- Clarifies navigation
- Improves editorial decisions
Modular authoring
Compose stable concept, procedure, reference, example, decision, and troubleshooting modules.
- Reduces duplication
- Supports reuse
- Improves ownership and freshness
Every Page Is Page One
Design each topic to orient readers who arrive through search, a deep link, a ticket, or an agent.
- Improves nonlinear discovery
- Strengthens deep links
- Reduces sequence dependence
Docs-as-code
Apply version control, pull requests, CI, automated builds, issue tracking, and shared ownership.
- Controls change
- Creates review history
- Connects docs to releases
Docs-as-tests
Treat documented commands, code, links, workflows, and assertions as testable product behavior.
- Finds drift
- Tests examples
- Validates end-to-end procedures
Specification-first
Generate exact reference from machine-readable contracts, then add curated examples and guidance.
- Reduces API drift
- Supports tooling and agents
- Improves validation
C4 model
Explain software architecture through progressively detailed context, container, component, and code views.
- Clarifies boundaries
- Supports audience-specific zoom
- Improves system orientation
arc42
Use a structured architecture coverage model for context, constraints, runtime, deployment, risks, and quality.
- Prevents architecture gaps
- Links quality to design
- Supports enterprise review
Architecture Decision Records
Capture one significant decision with context, alternatives, consequences, status, and validation evidence.
- Preserves rationale
- Supports supersession
- Improves accountability
Minimalist instruction
Start with meaningful action, reveal only necessary context, and treat errors as expected recovery points.
- Reduces startup friction
- Protects procedure flow
- Accelerates first success
| Failure mode | Primary method | Supporting method | Evidence of improvement |
|---|---|---|---|
| Content is accurate but irrelevant | User-needs design | Task analysis | Validated need and task completion |
| One page tries to serve every reader | Diátaxis | Modular authoring | Clear dominant page intent |
| Facts drift after product changes | Docs-as-tests | Specification-first | Executable examples and schema validation |
| Architecture lacks rationale | ADR | arc42 | Decision history and explicit consequences |
| Readers land midstream and get lost | Every Page Is Page One | Diátaxis | Independent orientation and deep links |
| Documentation cannot scale across teams | Modular authoring | Docs-as-code | Reuse, ownership, and traceable review |
A seven-stage operating system.
The sequence converts research into structured, testable, governed documentation. Select a stage to inspect its purpose, outputs, and gate.
Discover the user need
Establish evidence before deciding what to write or how to present it.
- Identify the specific audience, situation, and desired observable outcome.
- Review support incidents, onboarding friction, search behavior, interviews, and existing workflows.
- State what the reader already knows and what they must know next.
- Define scope, exclusions, constraints, and the evidence supporting the need.
Gate
The need can be expressed without naming a preselected page, component, or product feature.
Design the information intent
Choose the documentation form that matches the reader’s state and question.
- Use a tutorial for guided learning through action.
- Use a how-to guide for a real task and known goal.
- Use reference for exact facts, contracts, defaults, and limits.
- Use explanation for rationale, mechanisms, relationships, and trade-offs.
- Use ADRs, architecture views, runbooks, or showcases for their distinct operational purposes.
Gate
The artifact has one dominant intent and links to adjacent intents rather than blending them.
Decompose into stable modules
Create reusable units around one question, task, decision, or contract.
- Classify modules as concept, procedure, reference, example, decision, warning, troubleshooting, or evidence.
- Assign stable identifiers, ownership, status, version scope, and verification dates.
- Keep each module understandable from a nonlinear entry point.
- Reuse only when the module remains coherent in every target context.
Gate
Each module has one purpose and does not depend on a hidden reading sequence.
Author with a typed pattern
Use a structure appropriate to the module rather than a generic page template.
- Concept: definition, importance, relationships, model, example, boundaries.
- Procedure: outcome, prerequisites, steps, expected states, verification, recovery.
- Reference: scope, exact contract, defaults, constraints, examples, errors.
- Explanation: question, context, mechanism, model, trade-offs, implications.
Gate
The page structure follows the reader’s cognitive or operational path, not the product’s internal organization.
Prove important assertions
Classify evidence and automate verification wherever the behavior is deterministic.
- Label claims as generated, executable, reviewed, observed, proposed, or inferred.
- Run code, commands, API calls, links, and documented workflows.
- Validate examples against schemas and supported versions.
- Require human review for meaning, risk, comprehension, and user relevance.
Gate
No persuasive or operationally significant claim is presented without its evidence state.
Deliver through shared truth
Publish to multiple surfaces without duplicating authoritative facts.
- Use structured source content for documentation sites, explainers, exports, and agent context.
- Keep showcase, guide, handbook, reference, and research layers visibly distinct.
- Provide semantic HTML, stable anchors, explicit metadata, and machine-readable interface contracts.
- Preserve print, deep-link, keyboard, reduced-motion, and mobile behavior.
Gate
The interactive experience is not the only place where critical technical truth exists.
Observe reader outcomes
Measure whether documentation changes behavior and remains current.
- Track first-success time, task completion, recovery, retrieval, comprehension, and escalation.
- Inspect failed searches, abandoned procedures, repeated incidents, and stale ownership.
- Revalidate after product, policy, interface, or operational changes.
- Split, merge, promote, rewrite, or retire content based on evidence.
Gate
The team can state how the page’s effectiveness and freshness will be evaluated.
Start from an information contract.
Select a template. Copy it into a repository, prompt, design brief, or content-management workflow.
Verification is layered.
Automation verifies deterministic properties. Human review verifies meaning, relevance, risk, and comprehension.
Automated gates
Run these checks continuously in the authoring pipeline.
- Build, Markdown, and HTML validation
- Internal and external link checks
- Unique headings and stable anchors
- Terminology and style linting
- Executable code and command examples
- Schema and API-example validation
- Accessibility and metadata checks
- Freshness and ownership policies
Human gates
Use expert and representative-reader review for these dimensions.
- Valid user need and dominant intent
- Technical accuracy and realistic examples
- Security, privacy, and operational implications
- Correct mental model and diagram abstraction
- Visible boundaries and unsupported cases
- Task completion and recovery clarity
- Appropriate evidence for persuasive claims
- Comprehension by the intended audience
Evidence classification
Use six states: generated, executable, reviewed, observed, proposed, and inferred. A polished presentation must never disguise a proposed or inferred claim as established behavior.
Score the strength of a document.
Rate each dimension from zero to four. Production documentation should have no zeros, an average of at least three, and accuracy, executability, and accessibility at three or above.
Improve the system in four phases.
Start with the decisions that change output quality immediately. Add structure, verification, and outcome measurement in sequence.
Phase 1
Immediate controls
- Documentation brief
- User-need statement
- Diátaxis classification
- Page metadata
- Claim-evidence labels
- Typed templates
Phase 2
Structural scale
- Modular source content
- Stable identifiers
- Shared terminology
- Reusable prerequisites
- C4 and arc42 coverage
- ADR decision history
Phase 3
Verification
- Prose and markup linting
- Link checks
- Executable examples
- Schema validation
- Accessibility CI
- Freshness checks
Phase 4
Outcome optimization
- Time to first success
- Task completion
- Search success
- Escalation reduction
- Comprehension testing
- Retirement workflow
Operating rule
The showcase earns attention. The explainer builds the model. The guide enables action. The reference establishes truth. The tests preserve trust. The evidence constrains the hype.
Primary methods and standards.
The document synthesizes established documentation, architecture, accessibility, API-description, and software-delivery practices.
Information architecture and content design
DiátaxisTutorial, how-to, reference, and explanation classification.↗
GOV.UK user needsUser-centered content design and evidence-based need statements.↗
Nielsen Norman Group: Task AnalysisTask research, decomposition, sequence, complexity, and dependencies.↗
DITA topic architectureTopic-based structured authoring.↗
Red Hat Modular DocumentationConcept, procedure, and reference modules assembled around user stories.↗
Workflow, testing, and quality
Write the Docs: Docs-as-codeVersion control, collaboration, review, and automated publishing.↗
Doc DetectiveExecutable testing of documented browser, API, shell, and code workflows.↗
ValeConfigurable prose linting for terminology and style.↗
DORA documentation qualityClarity, findability, reliability, and organizational performance.↗
Architecture and technical contracts
C4 modelProgressive architectural views and system orientation.↗
arc42Architecture communication template and coverage model.↗
Architecture Decision RecordsDecision context, status, rationale, and consequences.↗
OpenAPI Specification 3.2Machine-readable HTTP API descriptions.↗
Arazzo SpecificationMachine-readable multistep API workflows.↗