Skip to content

Documentation

Source: hooks/ways/documentation/documentation.md

Frontmatter
Field Value
description documentation as a typed graph — taxonomy, catalog frontmatter, linting, and how docs are organized and serialized for readers
vocabulary documentation docs catalog taxonomy diataxis frontmatter markdown linting graph node edge serialization readme reference tutorial how-to explanation mode domain mkdocs obsidian altitude invariant type-checker serialize dangling
pattern catalog|diataxis|taxonomy|doclint|document.{0,30}(structure|model|graph|classif)
files README.md$|docs/.*.md$|mkdocs.ya?ml$
refire 0.15
macro prepend
scope agent, subagent
requires ['Bash(chmod:)', 'Bash(cp:)', 'Bash(mkdir:)', 'Bash(touch:)']

Documentation is one typed graph. Each page and each decision record is a node, and its related and supersedes references are edges. A node's type lives in its frontmatter, and a linter enforces it; the filename carries no type. The filesystem lays the graph out for human readers: folders, file names and the rendered site are views of the graph. Rearrange them freely, because the frontmatter stays the source of truth.

A person would take minutes to check the graph's types and links by hand, and an agent with a linter checks them in one pass. So keep the structure in frontmatter and in the linter, where it is cheap to maintain, and keep the folders easy for people to browse. (Decision: ADR-302.)

Two levels

The children of this way cover two levels: the model, which defines the graph's types, and the craft of writing one page or record well:

Level Concern Way
Model The graph itself — nodes, edges, one corpus for docs + decisions graph (forthcoming)
Model The typed node — id (DD.NNN.P), domain, mode, aliases, edges frontmatter (forthcoming)
Model The classification enum — Diátaxis reader posture (T/H/R/E) diataxis (forthcoming)
Model A node type — the decision record adr
Model The type-checker — doclint, the invariant set, the coverage matrix linting (forthcoming)
Model Projecting the graph for human readers — folders, nav, mkdocs, Obsidian serialization (forthcoming)
Craft The README, the page a newcomer opens first readme
Craft The CLAUDE.md or AGENTS.md file every session in a repository loads instruction-files
Craft Reference for HTTP/REST surfaces api
Craft Code-level docs (docstrings, JSDoc, rustdoc) docstrings
Craft Structural diagrams mermaid
Craft House norms — style, conventions, accessibility standards
Craft A cold read by a fresh agent, and a linter proven by a planted defect validate

The model ways marked forthcoming get written as ADR-302 is implemented. Until then, this parent lists them so that each one has a place in the corpus.

Principles

  • One graph, many views. Each page's type is set once, in its frontmatter, and the graph is rendered as several views: the dev tree, the published site, an Obsidian graph, and bundles for one audience. The audience decides which view it reads, and never changes a page's type.
  • Add a lint rule only when breaking it is a real defect, such as a link to a missing page, a cycle of supersessions, or an id that disagrees with its mode. A rule that catches no defect still costs maintenance.
  • Overview before detail, organized by the reader's task, and kept current. An outdated page misleads every reader who opens it.

See Also

  • adr(documentation) — decision records as nodes in the graph
  • readme(documentation) — the README, the first page a newcomer reads
  • standards(documentation) — documentation house norms
  • mermaid(documentation) — structural diagrams
  • validate(documentation) — a fresh agent given only the entry point grades the docs; a wrong answer is a docs defect
  • instruction-files(documentation) — the CLAUDE.md or AGENTS.md file every session loads
  • writing/plain(writing) — plain sentences, the present tense and terms defined on first use in a page