Documentation: Link, Don't Duplicate
Write documentation that points to the single source of truth instead of
restating it. A fact copied into a second place is a fact that will drift — the
copy goes stale the moment the original changes, and nothing flags it. This is
DRY applied to prose.
The principle
- Link from where the reader starts. Put a short pointer at the entry point
someone actually lands on (CLAUDE.md, README, a top-level index) that links to
the deep doc. Don't reproduce the deep doc at the entry point.
- One canonical home per fact. Each piece of information lives in exactly one
authoritative place; everywhere else references it.
- A runnable artifact is its own doc. When a skill, playbook, justfile
recipe, or script both does the thing and explains it, that artifact is the
documentation. Link to it — do not write a parallel prose copy that has to be
kept in sync by hand.
- Reference the authoritative source, not a hand-copy. When you must
enumerate (repos, packages, endpoints, flags), point at the source that's
already maintained — e.g. "the
comfy_registry = true entries in
repositories.tf" — rather than transcribing a list that silently falls out of
date.
When this bites
| Smell |
Why it drifts |
Do instead |
| A hand-maintained list mirroring config/code |
The source changes; the list doesn't |
Reference the source ("see the X entries in Y") |
| A command sequence copied into a doc and a script |
One gets edited, the other rots |
Keep it in the script; the doc links to it |
| The same workflow as prose and as a skill/playbook |
Two copies, two truths |
The skill is the doc; link to it |
| A config table duplicated across two READMEs |
Updates land in one |
One canonical doc; the other links |
| Re-explaining at the entry point what a deeper doc already covers |
Entry point and deep doc disagree over time |
Short pointer + link |
When duplication is acceptable
- A one-line summary at the entry point (with a link to the full source) is a
signpost, not duplication. Keep it to the gist, not the detail.
- Small, stable facts (a default value cited inline) can be repeated when
restating is clearer than a link — but prefer the link if the fact can change.
Litmus test before adding docs
Ask: "Does this fact already live somewhere authoritative?" If yes, link to it.
If you're about to type a second copy of something that exists elsewhere, stop
and reference the original. The best documentation edit is often a pointer, not a
paragraph.
Rationale
Duplicated documentation doesn't just waste effort — it actively misleads,
because a stale copy still reads as authoritative. Linking from entry points
keeps docs discoverable without creating mirror copies that diverge. Referencing
the source-of-truth means the docs can't go stale relative to it, because there's
only one truth. This is the prose analogue of DRY (~/.claude/rules/code-quality.md) and the
docs-side complement of ~/.claude/rules/local-ci-parity.md (one definition, consumed in many
places).
Related
blueprint-plugin:blueprint-docs-currency — the timing sibling: code and
the docs describing it land in the same commit.documentation-plugin:docs-sync — the mechanical catalog reconciler that
repairs drift after the fact in generated skill/command/agent tables.code-quality-plugin:dry-consolidation — the code-side analogue (clone
detection and shared-abstraction extraction over source).
1---2name: docs-single-source3description: Link docs to the single source of truth instead of restating it. Use when writing or restructuring docs, editing a README/CLAUDE.md, or copying a list that lives in code.4---5
6# Documentation: Link, Don't Duplicate
7
8Write documentation that **points to the single source of truth** instead of
9restating it. A fact copied into a second place is a fact that will drift — the
10copy goes stale the moment the original changes, and nothing flags it. This is
11DRY applied to prose.
12
13## The principle
14
15- **Link from where the reader starts.** Put a short pointer at the entry point
16 someone actually lands on (CLAUDE.md, README, a top-level index) that links to
17 the deep doc. Don't reproduce the deep doc at the entry point.
18- **One canonical home per fact.** Each piece of information lives in exactly one
19 authoritative place; everywhere else references it.
20- **A runnable artifact is its own doc.** When a skill, playbook, justfile
21 recipe, or script both *does* the thing and *explains* it, that artifact is the
22 documentation. Link to it — do not write a parallel prose copy that has to be
23 kept in sync by hand.
24- **Reference the authoritative source, not a hand-copy.** When you must
25 enumerate (repos, packages, endpoints, flags), point at the source that's
26 already maintained — e.g. "the `comfy_registry = true` entries in
27 `repositories.tf`" — rather than transcribing a list that silently falls out of
28 date.
29
30## When this bites
31
32| Smell | Why it drifts | Do instead |
33|---|---|---|
34| A hand-maintained list mirroring config/code | The source changes; the list doesn't | Reference the source ("see the X entries in Y") |
35| A command sequence copied into a doc *and* a script | One gets edited, the other rots | Keep it in the script; the doc links to it |
36| The same workflow as prose *and* as a skill/playbook | Two copies, two truths | The skill is the doc; link to it |
37| A config table duplicated across two READMEs | Updates land in one | One canonical doc; the other links |
38| Re-explaining at the entry point what a deeper doc already covers | Entry point and deep doc disagree over time | Short pointer + link |
39
40## When duplication is acceptable
41
42- A one-line *summary* at the entry point (with a link to the full source) is a
43 signpost, not duplication. Keep it to the gist, not the detail.
44- Small, stable facts (a default value cited inline) can be repeated when
45 restating is clearer than a link — but prefer the link if the fact can change.
46
47## Litmus test before adding docs
48
49Ask: *"Does this fact already live somewhere authoritative?"* If yes, link to it.
50If you're about to type a second copy of something that exists elsewhere, stop
51and reference the original. The best documentation edit is often a pointer, not a
52paragraph.
53
54## Rationale
55
56Duplicated documentation doesn't just waste effort — it actively misleads,
57because a stale copy still reads as authoritative. Linking from entry points
58keeps docs discoverable without creating mirror copies that diverge. Referencing
59the source-of-truth means the docs can't go stale relative to it, because there's
60only one truth. This is the prose analogue of DRY (`~/.claude/rules/code-quality.md`) and the
61docs-side complement of `~/.claude/rules/local-ci-parity.md` (one definition, consumed in many
62places).
63
64## Related
65
66- `blueprint-plugin:blueprint-docs-currency` — the timing sibling: code and
67 the docs describing it land in the same commit.
68- `documentation-plugin:docs-sync` — the mechanical catalog reconciler that
69 repairs drift after the fact in generated skill/command/agent tables.
70- `code-quality-plugin:dry-consolidation` — the code-side analogue (clone
71 detection and shared-abstraction extraction over source).
laurigates