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