Skip to content
All posts
  • Tutorial
  • Screenshots
  • Product

How to record step‑by‑step guides people follow

The best how‑to docs pair numbered steps with a screenshot per step — and die when the UI drifts. The workflow for guides that stay true: record once, screenshot per step, annotate, re‑verify.

Saksham Sharma3 min read

A step‑by‑step guide fails in one of two ways: the reader can’t follow it, or the reader follows it and the screenshots turn out to be of an interface that no longer exists. Both failures come from the same mistake — writing the guide from memory instead of from a recording. Here’s the workflow that fixes both, and it starts the same way a bug report does.

Record the task before you write a word

Do the task, on screen, exactly as a reader will — from a cold start, no shortcuts a newcomer wouldn’t know. Don’t try to capture the perfect screenshot live; you’ll fumble mid‑task and re‑do it. The recording is the source of truth: play it back and watch yourself find the menu you’d have sworn was in the sidebar. The false steps you skip on muscle memory are precisely the steps a newcomer needs written down.

This is the same insight as writing a bug report from the recording, pointed the other direction: memory writes confident, wrong guides; the recording writes right ones.

One step, one sentence, one screenshot

Write each step as a single sentence starting with a verb, and give it exactly one screenshot — the frame showing the state after the action, with the click target already marked. Two sentences means two steps. Zero screenshots means the reader is matching your words against a live UI alone, which is where guides lose people.

The annotation matters more than the screenshot: a numbered callout on the exact button turns “look at this full window” into “click this red 2.” Tools differ in how fast this goes — CleanShot X has the annotation tray, Snagit is built for guide‑making at scale, and in Snapbak the callouts and the OCR text grab sit beside the capture — the screenshot and its marker in one pass. Disclosure for the road: I make Snapbak; all three tools make good guides, and the workflow below is tool‑agnostic.

Screenshot hygiene that ages well

Guides die when the UI drifts, and you can’t stop the drift — but you can make re‑verification cheap:

  • Capture at a consistent window size, every time, so the shots align when one needs replacing.
  • Leave sensitive fields redacted at capture time, not cropped later — on‑device redaction before the shot enters the doc, because a guide with a real customer’s email in step 3 is a leak with documentation.
  • Name the shots to match the steps (guide‑03‑export‑dialog), so the re‑shoot after the next UI change is an afternoon, not an archaeology dig.

Video where the words fail

Some steps can’t be shot — a drag with modifier keys, a flow that only makes sense in motion. That’s the one place a recording embed earns its weight: keep it short, zoomed to the region, and paired with the written steps rather than replacing them. Written steps stay searchable and skim‑able; video proves the motion. The transcript‑trimmed demo format keeps such clips tight, and the GIF export covers the cases where the doc platform won’t take video.

The re‑verify loop

Before publishing, follow your own guide on a machine (or account) that hasn’t seen the task. Every place you hesitate is a missing step; every place you deviate from the guide is a wrong step. Fix both, and date the guide — future‑you re‑verifying against a date does the job, future‑you trusting the doc does not.

Snapbak is free for the first 100 users: download it, record your next “how do I…” question once, and turn the answer into the guide you’ll stop rewriting.