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.

Weak: Customer info

Check the customer details and handle any issues before continuing.

Why: Two actions and no test: every person does it differently, and nothing is recorded.

Strong: Confirm the customer's identity

Ask for the order number and the email on the account. Continue only if both match the order.

Why: One action, a clear test, and two required fields that record what was checked.

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.

Weak: Shipping damage

Our carriers sometimes damage parcels, and over the years we have seen many kinds of damage, from crushed boxes to water. Because claims depend on evidence, it is important that you photograph the damage before anything else happens to it.

Why: The instruction is the last sentence of a paragraph of background.

Strong: Photograph the damage

Take a photo of each damaged item and of its packaging, and attach them below. The carrier's claim depends on the packaging, so photograph it before it is thrown away.

Why: The action comes first; the reason follows in one line.

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.

Weak: Check refund eligibility

See the Refund Policy reference.

Why: The rule the step depends on is hidden in the reference, so the step can be finished wrong without ever opening it.

Strong: Check refund eligibility

Approve only when the purchase is less than 30 days old and the item is unused. For exceptions, see the Refund Policy.

Why: The decision rule is in the step; the edge cases stay in the reference.

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.

Weak: Refund or credit

Is the customer eligible, and would they prefer a refund or store credit?

Why: Two questions at one branch point: the paths cannot map cleanly to the answers.

Strong: Within the refund window?

Is the purchase less than 30 days old? Choose Yes or No. The next step asks whether the customer wants a refund or store credit.

Why: One question, one criterion, one path per answer; the second question gets its own step.

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.

Weak: Notes on every step

A free-text field labelled "Notes" at the end of each step, never required.

Why: It captures nothing the process needs, so the trail fills with empty or inconsistent notes.

Strong: Damage type

A required dropdown labelled "Damage type", with Crushed, Wet and Missing items, and a connection for each.

Why: It records exactly what the process needs, and the answer decides the next step.

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