How to turn a folder of screenshots into a written guide

Why documentation like this rots

Writing a step-by-step guide in a word processor means the pictures and the words are welded together in one binary file. When the software changes, updating it means opening the document, finding each screenshot, deleting it, pasting a new one, and fixing the layout that just moved.

That is enough friction that it does not get done, and six months later the guide shows an interface nobody recognises, which is worse than no guide because people follow it.

Keep the two apart and the economics change. Images in a folder, captions in a text file, one command to build the document. Re-taking the screenshots becomes the only real work, and the words survive.

The layout that works

onboarding/
  01-login.png
  02-dashboard.png
  03-settings.png
  steps.txt

Numbered filenames, because that fixes the order without any metadata. A plain-text steps file with one stanza per image: a heading, and a sentence or two of what the reader should do. Nothing else.

The result is something you can diff, put in version control, and hand to somebody who does not have the same software as you.

Getting the screenshots right

Show enough and no more. A full-screen capture of a 4K monitor to show one dialog wastes the reader’s attention. Crop to the window or the region that matters.

Be consistent. Same window size, same theme, same zoom, same demo account across the whole sequence. Inconsistent screenshots make a guide feel unreliable even when every step is correct.

Point at the thing. One arrow or one box, in a colour that is not in the interface. Not five annotations on one image — if a step needs five, it is five steps.

Use fake data. Never a real customer name, a real address, or a real order number. This is not only a privacy matter: real data ages, and a guide showing an order from 2023 looks abandoned.

Redaction, done so it stays redacted

The mistake people make is blurring. A blur is a reversible transform applied to information that is still there, and pixelated or blurred text has been recovered often enough to be a known genre of incident. The same goes for a semi-transparent shape over a value.

Cover it with a solid, opaque rectangle. Then, if the guide matters, open the exported image and confirm the value is gone rather than trusting the editor’s preview.

When you are redacting the same field across forty support screenshots, do it from a file of coordinates rather than by hand. Consistency is the point: an editor by hand will miss the fortieth one, and it only takes one.

The programs for this

• SnapDocs is the single-folder case. init scans a folder of images in sorted order and writes a starter steps file with an empty stanza per image, so the writing is filling in blanks. build produces one self-contained HTML file with every image embedded, which means it can be emailed and opens with no server and no missing-image boxes. check tells you if the folder and the steps file have drifted apart.
• DocSnap does the same across many folders at once — twenty ticket folders in, twenty documents out, one command — which is the version you want when this is a routine.
• StepShot takes a manifest and publishes to HTML, DOCX and Markdown, with a ledger of what was built. This is the one for when the output has to be a Word file somebody else edits.
• CaptureFlow does the annotation and redaction in bulk: drawing operations applied in the order given, and redaction driven by a regions file so forty screenshots get the identical treatment.

Free while we are in preview, one file each, Windows and Mac.

Taking the screenshots

None of these capture the screen — that needs operating-system APIs and is a different job. Use what you have: Win+Shift+S on Windows, Cmd+Shift+4 or Cmd+Shift+5 on macOS. Both let you capture a region or a single window, and both can be set to save straight into a folder, which is exactly the input these want.