LibraryKeep references close to what they supportv2 · Updated Report

Keep references close to what they support

This is a recommendation, not a requirement. Use it when a document contains claims, decisions, constraints, methods, or evidence that another document owns.

The recommendation

Put each reference beside the statement it supports. Name the relationship in the surrounding sentence: source, rationale, constraint, evidence, implementation detail, or canonical owner. A link shows that two documents are connected; the sentence should explain why.

This is semantic locality. The reference does not have to interrupt every sentence, but a reader should not have to search elsewhere in the document to discover what a link supports. Oddlynew's citation and backlink mechanics are explained in References and backlinks.

Why it helps

A local reference lets a person or agent assess provenance, authority, and drift while reading the claim. It also gives the graph a useful meaning: this edge exists because this statement depends on that source.

A generic list of related documents moves that work onto the reader. They must reopen every target, infer the relationship, and decide which statements each link belongs to. Such lists also accumulate easily after their purpose has disappeared.

When a separate list is right

Use a reference section when the list itself has a coherent job:

  • a bibliography for a document grounded throughout in the same body of sources;

  • an index or reading route whose purpose is navigation;

  • a short set of documents that genuinely constrain the entire document;

  • a provenance record where preserving the source set is itself important.

Name that job precisely. “Sources,” “Strategic boundaries,” or “Further reading” is clearer than a generic “Related documents.” If different references play different roles, move them to the relevant statements.

Public and private knowledge

A nearby reference does not transfer authority or access. A public document must still state every claim and decision its public reader needs. A private target may provide provenance or additional context for authorized readers, but it cannot carry the public meaning. See One audience per organization. When a private organization adopts public guidance, follow Reference public guidance, then state your local rule.

A small loop

  1. Find the statement whose source, rationale, constraint, or owner lives elsewhere.

  2. Put the reference beside that statement.

  3. Say what relationship the target has to it.

  4. Remove any bottom-list entry that has no remaining document-wide purpose.

  5. Keep a separate list only when the list itself helps the reader.

Example

Instead of ending a strategy with “Related documents: Pricing, Architecture, Free tier,” write: “The free-tier rationale lives in Free tier. Exact customer promises live in Pricing. The no-inference cost mechanism is explained in Architecture.” Each reference now has one understandable job.

Relationship to distillation

This complements Distill, do not accrete. Distillation keeps each answer in its owner; local references make the boundaries between those owners legible.

A useful prompt

Ask your agent: “Review this document's references. Move each one beside the claim, decision, constraint, method, or evidence it supports, and state the relationship in the surrounding sentence. Keep a separate reference list only when the list has a clear document-wide purpose.”

Oddlynew PublicSign in

Referenced by