Research rebuild · July 2026

Build documentation as a governed knowledge product.

A modern documentation system separates canonical truth from audience-specific delivery. It models user intent, typed content, technical contracts, workflows, evidence, and operational ownership before choosing the visual surface.

See the core model Audit an artifact

12 primary sourcesHuman and machine consumersSingle-file and print safe

01 · Orientation

Documentation fails before writing begins.

The recurring failure is not weak prose. It is an undefined communication problem, an implicit source of truth, or a representation chosen before the information relationship is understood.

Decision

Purpose and outcome

Who must understand, decide, or do what? What observable change proves success?

Knowledge

Objects and relationships

Claims, concepts, procedures, contracts, decisions, risks, evidence, and typed links.

Representation

Views matched to questions

Prose, diagrams, matrices, workflows, examples, and conformance states are selected by intent.

Delivery

Channels and overlays

A shared core produces role-specific sites, SPAs, references, exports, and agent context.

Audit

Evidence and operation

Source precedence, verification status, ownership, freshness, and measurable reader outcomes.

02 · Research synthesis

Complementary methods form one system.

No single methodology governs discovery, structure, exact truth, workflow, delivery, accessibility, and measurement. The model below assigns each practice a specific job.

User need and task evidence

Start with the situation, current path, friction, and desired result.

content designtask analysis

Prevents: accurate content that does not help anyone complete a real task. Output: a measurable content contract and task model.

Reader intent

Separate tutorial, how-to, reference, and explanation concerns.

Diátaxis

Prevents: pages that teach, persuade, instruct, and specify at the same time. Output: one dominant purpose per artifact.

Typed modular content

Use topics and maps to assemble coherent deliverables from reusable units.

DITA 2.0Red Hat modular docs

Prevents: duplicated prerequisites, drifting definitions, and monolithic pages. Output: concepts, procedures, references, and assemblies with stable IDs.

Machine-readable truth

Define contracts, constraints, annotations, links, and custom vocabularies.

OpenAPI 3.2JSON Schema 2020-12

Prevents: reference drift and ambiguous requirements. Output: schemas that support validation, documentation, navigation, and tooling.

Outcome workflows

Represent sequences and dependencies required to achieve a result.

Arazzo 1.1

Prevents: disconnected endpoint descriptions that never explain the actual job. Output: human- and machine-readable workflows.

Controlled transformation

Apply repeatable updates, removals, or copies to a canonical description.

OpenAPI Overlay 1.1single source

Prevents: manually forked public, partner, internal, and role-specific documentation. Output: governed overlays that preserve the core.

Delivery, accessibility, and outcomes

Integrate review, tests, WCAG, stable anchors, freshness, and usage evidence.

docs-as-codeWCAG 2.2DORA AI-accessible data

Prevents: visually polished but stale, inaccessible, or unmeasured output. Output: a release pipeline and operational quality signals.

03 · Intent architecture

Separate the reader’s mode before composing the page.

Diátaxis remains the strongest editing lens for core documentation. Enterprise delivery adds adjacent artifact types for decisions, architecture, operations, and showcase communication.

Learning · Action

Tutorial

Build skill through a controlled, successful experience.

Teacher owns the sequence
Minimize branching
Produce visible progress
Explain only what supports learning

Working · Action

How-to guide

Move a competent reader through a real-world problem field.

Lead with the outcome
State prerequisites and choices
Show verification and recovery
Link exact contracts

Learning · Information

Explanation

Build a mental model of mechanisms, relationships, rationale, and trade-offs.

Answer a conceptual question
Use representative examples
Compare credible alternatives
Distinguish fact from inference

Working · Information

Reference

Describe exact behavior, contracts, defaults, constraints, and compatibility.

Product-led structure
Stable identifiers
Normative terminology
Validated examples and errors

Enterprise extension: showcases earn attention, architecture views establish system context, ADRs preserve decisions, and runbooks restore service. They should link into—not blur—the four core documentation intents.

04 · Core truth and overlays

Model once. Assemble and transform deliberately.

This is the central research upgrade. DITA maps, JSON Schema vocabularies, OpenAPI descriptions, Arazzo workflows, and Overlay transformations all support a composable model: stable core knowledge plus controlled views.

Evidence

Source inputs

Code, schemas, tests, decisions, research, operations, and user evidence.

Core

Knowledge objects

Concepts, procedures, contracts, claims, risks, examples, and owners.

Map

Assemblies

Audience journeys, product hierarchies, relationship tables, and workflow sequences.

Overlay

Controlled views

Add metadata, remove restricted material, or adapt emphasis without forking truth.

Channel

Delivery surfaces

Documentation site, explainer SPA, API reference, PDF, IDE, CLI, or agent context.

Canonical artifact

Model gateway contract

Stable identifiers, exact interface behavior, authentication requirements, policy boundaries, examples, errors, owners, and evidence.

normative coreversionedvalidated

EXExecutive overlayEmphasize outcome, risk, investment, and decision.update

ENEngineer overlayAdd setup, examples, troubleshooting, and SDK guidance.update + copy

PAPartner overlayRemove internal topology and restricted operations.remove

AIAgent overlayAdd semantic intent, preconditions, side effects, and retrieval metadata.update

ESLocalization overlayAdapt language and examples while preserving IDs and contract terms.update

05 · Representation studio

One subject. Seven synchronized technical views.

A single visual treatment cannot answer every technical question. The selected subject remains stable while the representation changes.

Representation

verifiedv2.1internal

Governed model access

Route application and agent requests through identity, policy, model routing, observability, and evaluation controls.

Actor

Developer or agent

Requests an approved capability with an authenticated identity.

Control

Governed gateway

Evaluates policy, resolves a model, records attribution, and enforces limits.

Provider

Model endpoint

Executes the approved request without receiving unnecessary identity context.

Promise: one integration path for approved model access.

Boundary: the gateway does not make an unsafe use case acceptable.

Next action: select the integration procedure or inspect the contract.

Contract view

Exact fixed fields, patterned collections, defaults, constraints, and source-of-truth links.

Gateway request object
Field	Type	Status	Meaning	Constraint
`model`	`ModelRef`	Required	Approved logical model identifier.	Must resolve in the caller's policy scope.
`messages`	`Message[]`	Required	Conversation input.	At least one message; content policy applies.
`purpose`	`PurposeCode`	Required	Declared business use.	Must match an approved use-case record.
`timeoutMs`	`integer`	Optional	Caller timeout.	Default 30000; maximum 120000.
`metadata.<name>`	`string`	Patterned	Namespaced operational context.	Sensitive values prohibited.

outcome: accepted responseArazzo-inspired

Outcome workflow

Represent the sequence and dependencies required to deliver the result—not only the available endpoints.

1Resolve identityExchange workload identity for a scoped token.precondition

2Evaluate policyValidate purpose, entitlements, data class, and limits.depends on 1

3Resolve routeSelect provider and model according to approved policy.depends on 2

4Execute requestSend the minimized provider request and collect telemetry.depends on 3

5Return governed resultAttach request ID, policy decision, and usage metadata.outcome

Example hierarchy

Examples are typed assets: smallest valid, recommended production, boundary, and invalid.

minimal-request.json

Claim-to-source lineage

Every consequential claim exposes its authority, evidence, verification method, date, and owner.

ClaimExpired tokens are rejectedNormative behavior

SourceAuthentication contractauth.schema.json

ProofIntegration testexpired-token.spec.ts

Verified2026-07-18CI execution

OwnerPlatform identityTier 1

Authority precedence: schema and policy → generated reference → operational guide → explainer → showcase.

06 · Delivery and verification

Treat documentation changes like production changes.

Docs-as-code is the change mechanism. Docs-as-tests verifies deterministic claims. Accessibility and task testing validate the reader experience.

Discover

Validate audience and task evidence
Establish baseline outcome measures
Identify authoritative sources
Record uncertainty and exclusions

GateThe need exists independently of the proposed page.

Model

Assign typed objects and stable IDs
Define relationships and precedence
Select document intent
Define audience overlays

GateNo duplicate or competing source of truth.

Author

Use the typed content pattern
Pair claims with evidence
Provide valid and invalid examples
Design mobile transformations

GateThe representation answers a specific question.

Verify

Build, markup, and link checks
Execute code, commands, and workflows
Validate schema examples
Review security and accessibility

GateCritical claims are executable or reviewed.

Publish

Generate audience surfaces
Preserve stable anchors
Expose version and ownership
Provide print and machine context

GateChannel output does not fork core truth.

Observe

Measure task and search success
Track stale and unowned content
Inspect support and incident signals
Retire or supersede obsolete material

GateThe team knows when the artifact is failing.

07 · Reusable templates

Begin with an information contract, not a blank page.

The templates encode the operating model. They are intentionally compact so teams can adopt them without requiring a specialized authoring platform.

Template

Defines the communication problem and validation criteria.

documentation-brief.yaml

09 · Adoption and governance

Adopt the model in reversible layers.

Do not start with a new platform. Start by changing the decisions and metadata that control output quality, then automate the workflow.

Phase 1 · Contract

Standardize intent and evidence

Documentation brief
Typed artifact templates
Stable IDs and anchors
Authority and evidence states

Phase 2 · Knowledge

Separate core truth from delivery

Concept, procedure, and reference modules
Maps and relationship tables
Canonical interface schemas
Audience overlay policy

Phase 3 · Verification

Integrate documentation into delivery

Markup and link checks
Executable examples
Schema and workflow tests
Accessibility CI and human review

Phase 4 · Outcome

Operate documentation as a product

Task success and search metrics
Freshness and ownership dashboards
Support and incident correlation
AI retrieval quality evaluation

Documentation ownership, evidence, and review triggers
Role	Accountability	Required evidence	Review trigger
Product or capability owner	User need, priority, and business outcome.	Task evidence and adoption goal.	Scope or audience change.
Technical owner	Behavior, architecture, and source-of-truth accuracy.	Schema, tests, implementation, and decision links.	Interface or runtime change.
Documentation owner	Intent, structure, clarity, navigation, and lifecycle.	Content contract, review history, and freshness.	Support signal or stale date.
Security and governance	Classification, policy, rights, and exposure boundaries.	Control mapping and approval record.	Risk tier or channel change.
Representative reader	Task success and comprehension.	Observed completion and recovery evidence.	Major workflow or audience change.

10 · Sources and limits

Primary standards, methods, and evidence.

Research was refreshed on July 21, 2026. The synthesis combines official specifications and maintained guidance. Generalization beyond each source’s native domain is identified as analysis, not as a claim made by the source.

01DiátaxisFour documentation needs and a systematic approach to authoring.↗ 02DITA 2.0Topic-based architecture, maps, metadata, reuse, accessibility, and localization.↗ 03Red Hat Modular DocumentationConcept, procedure, reference, and assembly guidance.↗ 04OpenAPI 3.2Human- and machine-readable HTTP interface descriptions.↗ 05Overlay 1.1Repeatable update, remove, and copy transformations over OpenAPI descriptions.↗ 06Arazzo 1.1Sequences and dependencies expressed around API outcomes.↗ 07JSON Schema 2020-12Validation, documentation, navigation, interaction, dialects, and vocabularies.↗ 08DORA documentation qualityDocumentation quality as a capability associated with organizational performance.↗ 09DORA AI-accessible internal dataAccurate, accessible internal information as a foundation for effective AI adoption.↗ 10WCAG 2.2Stable accessibility requirements with supporting implementation and testing guidance.↗ 11Google accessible documentationSemantic structure, keyboard access, alternatives, formatting, and navigability.↗ 12Stable heading targetsDescriptive, durable anchors and compatibility when headings change.↗

Synthesis, not a new standard

The seven-stage operating model and core-plus-overlay documentation architecture are derived recommendations. They are not published as one combined external specification.

Use concepts proportionally

DITA, OpenAPI, Arazzo, and Overlay are formal technologies. Teams can adopt their representation principles without adopting every native format or tool.

Automation cannot prove comprehension

Build checks and executable examples preserve deterministic accuracy. Representative-reader testing is still required for task success and understanding.