Skip to main content

Writing effective bits

A bit is the smallest unit of a flow: the text and interactive elements that tell the person on a step what to do right now. The best bits are just-in-time — they carry exactly the instruction needed to act at this step, and leave stable background knowledge to a linked reference.

Give each bit one job — and let the title name it​

A bit should accomplish one step, and its title should name that step. A useful test: if you need "and" to describe what the bit does, it is probably two bits. Bits that bundle several steps or several decisions become hard to follow and hard to maintain — split them.

Lead with the action​

The first line should say what to do. Context, if the step needs any, comes after the action — it must never bury it. The classic failure is a wall of text with the actual instruction somewhere in the middle; the reader should not have to excavate the step.

Keep it as short as the step allows​

A bit should be as short as its step permits and contain one focused unit of work. Dense content — code, tables, evidence, required examples — is fine when it belongs to the current step. Length becomes a problem when a bit combines unrelated actions, separate decisions, or background and policy material that should be split into other bits or linked as a reference. If you have set a meaningful target completion time on the bit, use it as a sanity check on size; if you have not, treat time targets as a hint for review rather than a rule.

Make it self-sufficient — without becoming a policy manual​

Someone competent in the domain should be able to complete the step from the bit alone. Keep the minimum instruction to act in the bit; put deeper policy, full tables, and rationale in a linked reference. Two failure modes sit on either side of this line:

  • Restating a policy inline instead of linking the reference that owns it — the two copies drift apart over time.
  • Pushing information the reader must have into a reference — the step can then be completed wrong without ever opening it. This is the one bit-writing mistake that causes wrong outcomes, not just rough edges.

The fix for both is the same split: state the minimum decision rule in the bit (for example, "Approve only when the purchase is within the allowed window and condition requirements are met") and link the reference for the full policy and its edge cases.

Ask one question per branch point​

If a bit gates progress on a choice, it should ask exactly one question, state the criteria for answering it, and its outgoing connections should map cleanly to the answers. A bit that asks two questions at one branching point forces the reader to untangle them — split it into two decision steps.

Write to be scanned​

Name the thing being acted on — say what to click or open, not "click here". Use lists for sequential steps and for parallel options; keep paragraphs short and reserve them for context that genuinely does not fit a list. People run flows mid-task, often under pressure; a scannable bit respects that.

Add interactive elements only where they earn their place​

Include an interactive element only where input is genuinely captured or an action is genuinely tracked — never as decoration. An element that captures nothing and tracks nothing just adds noise to the step and to the trail record. Give each element a clear name that is unique within the bit, so the answers recorded against it are unambiguous.

Most of these criteria are graded, not gated: a bit that falls short still saves and runs, and the shortfall is content debt to improve. The exception noted above — step-critical information hidden in a reference — is a correctness problem, because the step can be finished wrong while looking finished.

Last reviewed: 2026-07-28