The 3x Documentation Scheme

A project-neutral system for explaining what, how, and why

Use one structured source to create a searchable project manual for people and agents. See the CLI and format reference for exact commands and fields.

Schema-drivenAgent-readableZero dependenciesStandalone HTML
The 3x reading contract: every entry explains what it does, how it works, and why it works that way.
No entries match that search.

The Core Model

The scheme documents observable behavior, implementation, and design intent as one reviewable unit.

The three-question contract

#
foundationreader contract

Every subject answers What, How, and Why in that order.

What it does

Provides a repeatable shape for documenting a component, command, workflow, policy, or architectural decision.

How it works

  1. What defines behavior, inputs, outputs, guarantees, and visible failure modes.
  2. How traces implementation, data flow, dependencies, and operational boundaries.
  3. Why records constraints, trade-offs, intent, and meaningful alternatives.

Why it works this way

Readers usually need all three perspectives but at different moments. Keeping them adjacent prevents reference material from drifting away from implementation detail or design rationale.

Evidence
  • Content contract scheme/manual.schema.json
  • Example source scheme/example.manual.json

Related: Manual structure · Facts, inference, and rationale

Manual structure

#
information architectureschema

Project metadata, presentation settings, sections, and entries remain separate but composable.

What it does

Organizes a manual into reader-oriented sections containing stable, linkable entries. Each entry can include a summary, synopsis, tags, evidence, and related-entry links in addition to its required triad.

How it works

The JSON hierarchy is deliberately shallow:

  1. Project metadata supplies reusable identity and version values.
  2. Manual metadata describes the document and its badges.
  3. Sections create navigation groups and entries carry the actual explanations.
  4. Theme values alter presentation without changing content.

Why it works this way

A predictable hierarchy is easy for humans to review, agents to generate, schemas to validate, and renderers to transform without parsing hand-authored HTML.

Evidence
  • scheme/manual.schema.json scheme/manual.schema.json
  • scripts/manual.py scripts/manual.py

Related: The three-question contract · Metadata and runtime overrides

Authoring a Manual

Good 3x documentation begins with project discovery and treats uncertainty explicitly.

Scope and inventory

#
planningaudience

Choose subjects by reader need, not merely by source-tree shape.

What it does

Identifies which capabilities, boundaries, workflows, policies, and decisions deserve entries and which audience the manual serves.

How it works

  1. Name the primary audience and the decisions they need to make.
  2. Inventory user-visible capabilities and operational workflows.
  3. Map architecture boundaries and consequential design decisions.
  4. Group subjects into a learning path, then assign stable kebab-case IDs.

Why it works this way

Mirroring folders produces implementation indexes rather than useful manuals. Reader-oriented scope keeps the document navigable and avoids exhaustive but low-value function commentary.

Evidence
  • README.md README.md

Related: Facts, inference, and rationale · Maintenance lifecycle

Facts, inference, and rationale

#
accuracyprovenance

Implementation claims require evidence; inferred rationale must be labeled.

What it does

Separates observed project facts from interpretation so readers can judge confidence and trace important claims.

How it works

  1. Write What from behavior that can be demonstrated or tested.
  2. Write How from inspected source, configuration, runtime behavior, and operational records.
  3. Write Why from decision records or maintainer statements when available.
  4. When intent is not recorded, say that the rationale is inferred and name the evidence supporting the inference.

Why it works this way

Plausible explanations are easy to invent and hard to detect later. Explicit provenance prevents a polished manual from becoming an authority for facts the project never established.

Evidence
  • README.md README.md
  • scheme/manual.schema.json scheme/manual.schema.json

Related: Evidence and relationships · Validation and visible gaps

Evidence and relationships

#
traceabilitynavigation

Entries expose their supporting artifacts and conceptual neighbors.

What it does

Attaches files, tests, decision records, commands, or URLs to claims and connects entries that readers commonly traverse together.

How it works

Evidence accepts a path string or a labeled target object. Related entries use stable IDs that the validator checks and the renderer turns into local links.

Why it works this way

Traceability shortens verification and maintenance. Explicit relationships add useful navigation without forcing the section hierarchy to represent every conceptual connection.

Evidence
  • scheme/manual.schema.json scheme/manual.schema.json
  • scripts/manual.py scripts/manual.py

Related: Facts, inference, and rationale · Validation and visible gaps

Dynamic Adaptation

The same content contract supports local writing, automated releases, CI checks, and agent-assisted maintenance.

Metadata and runtime overrides

#
automationconfiguration

Change shared values once or inject release-specific values during a build.

python3 scripts/manual.py build SOURCE --set project.version=2.0.0 --output index.html

What it does

Resolves metadata placeholders throughout the document and permits scalar values to be overridden from the command line.

How it works

  1. Place a double-braced path such as project.name or project.version in textual fields.
  2. The builder resolves placeholders against the source document before validation.
  3. Each --set PATH=VALUE assignment updates an existing scalar before resolution.

Why it works this way

Versions, names, URLs, and theme values recur throughout documentation. Central values and build-time injection prevent repetitive edits and make release automation deterministic.

Evidence
  • scripts/manual.py scripts/manual.py
  • tests/test_manual.py tests/test_manual.py

Related: Manual structure · Portable generation

Validation and visible gaps

#
quality gateCI

Incomplete triads fail; weaker traceability remains visible as a warning.

python3 scripts/manual.py check SOURCE

What it does

Checks required structure, stable IDs, dimension content, recognized placeholder text, evidence shape, and related-entry targets.

How it works

Structural defects and recognized unfinished-writing markers produce a nonzero exit. Missing evidence and unknown related IDs produce warnings that require judgment without blocking exploratory drafts.

Why it works this way

A manual should never silently present empty reasoning as complete. Separating errors from warnings preserves a firm minimum contract without pretending every quality concern can be decided mechanically.

Evidence
  • scripts/manual.py scripts/manual.py
  • tests/test_manual.py tests/test_manual.py
  • scheme/manual.schema.json scheme/manual.schema.json

Related: Facts, inference, and rationale · Portable generation

Portable generation

#
HTMLsearchprint

One validated source becomes one searchable, responsive HTML file.

python3 scripts/manual.py build SOURCE --output manual.html

What it does

Produces a standalone manual with navigation, full-text filtering, stable anchors, responsive triad cards, evidence disclosure, and print styles.

How it works

The standard-library generator escapes content, applies a deliberately small inline notation, embeds CSS and JavaScript, and writes a dependency-free HTML document.

Why it works this way

A single artifact is easy to preview locally, attach to a release, publish on any static host, archive, or inspect in restricted environments.

Evidence
  • scripts/manual.py scripts/manual.py
  • tests/test_manual.py tests/test_manual.py

Related: Metadata and runtime overrides · Maintenance lifecycle

Keeping It Alive

The scheme is most useful when documentation evolves with the project rather than following it later.

Maintenance lifecycle

#
workflowgovernance

Review documentation in the same change that alters documented behavior or rationale.

What it does

Treats manual source as maintained project material with validation in local workflows and continuous integration.

How it works

  1. Run check in CI for every proposed change.
  2. Use watch while restructuring or writing several entries.
  3. Update What when contracts change, How when implementation boundaries move, and Why when constraints or decisions change.
  4. Preserve entry IDs during title edits and review the built artifact before release.

Why it works this way

Documentation drift is primarily a workflow problem. Co-locating review and enforcing the minimum contract makes stale reasoning easier to catch when relevant context is still available.

Evidence
  • README.md README.md
  • scripts/manual.py scripts/manual.py

Related: Scope and inventory · Agent adaptation workflow

Agent adaptation workflow

#
agentshandoff

Agents use the same schema, evidence expectations, and validation gate as human authors.

What it does

Gives coding and documentation agents an explicit protocol for discovering, drafting, checking, and handing off a project manual.

How it works

  1. Read the schema and the project sources in scope.
  2. Inventory behavior and architecture before drafting entries.
  3. Cite implementation-specific claims and label inferred rationale.
  4. Preserve stable IDs, run validation and generation, then report warnings requiring human judgment.

Why it works this way

Structured outputs reduce ambiguity between tools and sessions. Using the human workflow also keeps agent-produced documentation reviewable instead of creating a separate, opaque automation path.

Evidence
  • README.md README.md
  • scheme/manual.schema.json scheme/manual.schema.json
  • tests/test_manual.py tests/test_manual.py

Related: Facts, inference, and rationale · Maintenance lifecycle