Skip to main content

Using references well

A reference is read-only supporting knowledge a person may consult during a step — policy, definitions, limits, matrices, rationale. If the bit is the just-in-time instruction, the reference is its just-in-case companion: helpful when the reader wants depth, never required to finish the step.

What belongs in a reference — and what doesn't​

The boundary is one question asked at each layer. Does the content tell the reader what to do at a step? That is a bit. Does the answer determine the next step? That is a branch in the flow. Is it stable, declarative knowledge the reader may consult but does not need in order to act? That is a reference. And if the reader must read it in full before the step makes sense, it belongs inline in the bit — not in a reference.

When in doubt, default to putting content in the bit. The cost of a missed reference is a quality nit; the cost of required information hidden in a reference is a wrong outcome.

Keep every reference optional​

The test: if removing the reference would make the workflow incomplete or confusing, that content belongs in the bit. A reference opens on top of the step, and nothing forces the reader to open it — so a step must be completable, correctly, by someone who never does. Keep the minimum decision rule in the bit itself and link the reference for the full policy, the rationale, and the edge cases.

Don't disguise procedures as references​

A reference states a rule, policy, definition, limit, or rationale — it never tells the reader what action to take next. Step-by-step instructions dressed up as a reference are really bits and should become bits. References are read-only by design and cannot contain interactive elements: they hold knowledge, they do not capture input or track actions.

Give it a clean, specific title​

A reference should form one coherent, bounded object with a specific title — "Refund Eligibility Policy", not "Misc Notes". If the best title you can find is vague, that is the signal to split the content into smaller pieces or not create the reference at all. Promoting a leftover grab-bag section to a reference just moves the mess somewhere with more authority.

Keep it authoritative and current​

Build references from official, accepted, current source material — not draft notes or stale examples. A published reference lends whatever it contains an air of authority, so unverified or outdated content does more damage there than it would anywhere else. When the underlying policy or knowledge changes, update the reference: the edit shows up immediately in every bit that links it.

Maintain once, use everywhere​

One reference can be linked from many bits across many flows, and a change to it propagates to all of them at once. That is the payoff of the split: a policy update becomes a one-place edit instead of a workflow redesign. Two habits protect it:

  • Before creating a new reference, check whether an existing library entry already owns that knowledge. If it does, link it — a second copy will drift from the first.
  • It is fine to create a reference before anything links to it; a library item awaiting use is valid.

Choose the scope deliberately​

Create a reference at the broadest scope where its knowledge is true — account-wide by default, and at an organization or group only when the knowledge is genuinely local to it. Scope is fixed at creation: a reference created at the wrong scope cannot be re-scoped and has to be recreated. Getting this right the first time keeps the reference usable everywhere it applies.

A good bit cites a good reference only where deeper detail helps, and never where it is required. Hold to that line and your references stay what they should be: a trustworthy layer of depth behind every step, not a place where critical instructions go missing.

Last reviewed: 2026-07-28