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 starts with a verified user need. It separates reader intent, selects the right representation, connects claims to technical truth, 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.
Choose the representation first
Sequence, comparison, hierarchy, dependency, contract, and state each require a different visual form.
Make interaction reveal causality
A control should expose what changed, why it changed, and which evidence or constraint applies.
Treat rendering as a release gate
Alignment, overflow, text scaling, themes, motion, mobile transformation, and print output require inspection.
Different methods solve different failure modes.
The strongest system combines complementary approaches. Use the filters to inspect the methodology by problem domain.
1NeedUser-needs design · task analysis
2IntentDiátaxis · minimalist instruction
3StructureModular authoring · Page One
4TruthSpecifications · tests · ADRs
5OutcomesFindability · success · freshness
Inspect the individual methods
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.
One technical subject. Six synchronized views.
OpenAPI demonstrates that the same technical truth can support human explanation, exact contracts, typed relationships, validated examples, conformance language, and provenance without creating six independent sources of truth.
Overview
A concise summary orients the reader before exact fields, implementation variants, or evidence details appear.
Purpose
Establish workload identity and policy context before a request is allowed to reach a model provider.
Guaranteed behavior
Expired or unauthorized tokens are rejected before request routing. Accepted identity is attached to platform telemetry.
Boundaries
- Does not approve the business use case.
- Does not guarantee model-provider availability.
- Does not replace operation-level authorization.
Next actions
- Register a workload identity.
- Configure the token audience.
- Run the sandbox verification request.
Contract
Fixed fields establish known semantics. Patterned fields provide controlled extension for named environments and policies.
| Field | Type | Status | Meaning | Default |
|---|---|---|---|---|
| audience | URI | Required | Gateway resource identifier the token is issued for. | None |
| subject | WorkloadRef | Required | Stable identity of the calling workload. | None |
| scopes | string[] | Required | Operation permissions evaluated before routing. | None |
| clockSkewSeconds | integer | Optional | Permitted clock difference during token validation. | 60 |
| telemetry | TelemetryPolicy | Optional | Identity fields retained in traces and audit events. | platform |
environments.
A patterned collection holds environment-specific issuer, audience, and trust-policy values without expanding the core field vocabulary.
Typed relationship graph
Edges state what a connection means. A relationship does not imply authorization, availability, or guaranteed success.
Workloadcaller
→obtains token from
Identity providerissuer
→presents token to
Model gatewayvalidator + policy
Model gatewayvalidated subject
→evaluates against
Authorization policydecision
→conditionally routes to
Model providerexecution target
obtains-token-frompresents-toevaluates-againstconditionally-routes-toobserved-by
Validated example hierarchy
Examples are classified by intent. They include inputs, expected results, environment scope, and validation state.
Smallest valid request
Authorization: Bearer
X-Model-ID: approved-v2 Valid non-production token with one model invocation scope.
Expected202 Accepted
Recommended request
Authorization: Bearer
X-Model-ID: approved-v2
X-Request-ID: 7f4... Workload identity plus a caller-supplied correlation identifier.
Expected202 Accepted
Expired token
Authorization: Bearer
X-Model-ID: approved-v2 Demonstrates rejection before routing and the structured recovery signal.
Expected401 Token expired
Conformance and behavior state
Normative vocabulary distinguishes obligations from recommendations, options, and behavior that cannot be depended upon.
Must
Production workloads authenticate through an approved workload identity.
AUTH-01Must not
Long-lived static credentials are not stored in application source or container images.
AUTH-02Should
Callers provide a stable request identifier to improve cross-system traceability.
OBS-03May
Local development uses a short-lived delegated credential under an approved exception.
DEV-04Undefined
Applications must not depend on undocumented claim propagation from a model provider.
INT-05Claim-to-source provenance
Each important statement carries an authority class and a concrete verification source.
Expired tokens are rejected before routing.
ExecutableValidated by the gateway integration suite against the supported token issuer.
test://gateway/authentication/expired-token
Workload identity is required in production.
NormativeEstablished by the accepted platform security decision and policy schema.
adr://core-platform-ai/0017-workload-identity
Request identity is attached to telemetry.
ObservedConfirmed in traces produced by the production-equivalent verification environment.
evidence://gateway/trace-correlation/2026-07-18
The design reduces onboarding time.
ProposedRequires baseline measurement and a production adoption cohort before publication as established value.
measurement-required://onboarding/time-to-first-success
Objects
Give each concept, procedure, operation, decision, example, and claim a typed identity.
object.id + object.typeRelationships
Use semantic edges such as depends-on, produces, validates, supersedes, and authorizes.
from + relation + toStates
Expose required, optional, default, deprecated, undefined, experimental, and verification states.
status + authority + evidenceVerification 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
- Viewport overflow, duplicate IDs, and deterministic responsive-layout checks
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
- Rendered inspection across mobile, desktop, light, dark, reduced-motion, and print states
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.
Start from a calibrated profile
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
- Typed object and relationship model
- Reusable prerequisites
- C4 and arc42 coverage
- ADR decision history
Phase 3
Verification
- Prose and markup linting
- Link checks
- Executable examples
- Schema and conformance 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.
The document carries its lineage.
Provenance is encoded in visible content, document metadata, HTML comments, and JSON-LD. Framework definitions trace to cited primary sources. Combined operating guidance is an explicit research synthesis.
Document record
- ID:
tdos-research-synthesis - Version:
1.4.0 - Created: 2026-07-18
- Last verified: 2026-07-18
Research synthesis
Definitions derive from the official methods, standards, and specification sources listed below. The seven-stage operating system is a synthesized recommendation, not a normative external standard.
Claim classification
Claims use generated, executable, reviewed, observed, proposed, or inferred evidence states. Proposed and inferred claims must remain visibly distinct from established behavior.
Change policy
Update the version and verification date when methodology coverage, source interpretation, responsive behavior, interaction semantics, or visual release gates materially change.
| Content class | Origin | Evidence status | Maintenance rule |
|---|---|---|---|
| Method definitions | Linked official sources and standards | Source-derived and reviewed | Recheck when the source publishes a new normative version |
| Seven-stage operating system | Synthesis across researched methods | Editorial recommendation | Revise when outcome evidence exposes a stronger sequence |
| Templates and quality gates | Synthesized implementation patterns | Reviewable and testable | Version with workflow or governance changes |
| Technical representation system | Synthesis of OpenAPI object, field, reference, example, and normative-language patterns | Source-derived pattern with editorial adaptation | Recheck against future OpenAPI normative revisions |
| Interactive rubric | Derived from the fifteen quality dimensions | Heuristic, not certification | Calibrate against reader and operational outcomes |
Primary methods and standards.
The document synthesizes established documentation, architecture, accessibility, API-description, technical-representation, 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.↗