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