Screenshots That Help, and the Ones That Do Not

Sunday, 02:05, at the out-of-hours branch of Pennywell Vets. Grace is the nurse on call, and a dog has just been admitted with a torn pad. The practice system needs the admission recorded tonight. Otherwise the drugs she is about to use will not come off stock and the owner will not be invoiced. She has never done an out-of-hours admission. There is an article, "How do I record an emergency admission?", and it has fourteen screenshots. Each one is the whole practice system window, shrunk to fit the page, so that the text in them is the height of a grain of rice. The one thing she needs is a tick box labelled "Out of hours" that the article's step 9 says to tick. It is somewhere in screenshot 9. She cannot find it on her screen because she cannot read it in the picture. She scrolls up and down between step 8's picture and step 9's text, which are a full screen apart. At 02:20 she writes the admission on paper for the morning team and goes back to the dog. The stock count is wrong for a day. The invoice goes out a week late. The article had fourteen pictures and showed her nothing.

A screenshot is a picture of part of the screen, placed in an article to show the reader where something is or what they should see. It is the most common visual in any knowledge base and the most misused, because taking one is free and the costs land later. They land on the reader scrolling past it, on the phone screen that cannot show it, and on the editor. The editor has to replace it when the screen changes. This article is part of our Writing KB Articles People Can Actually Follow series. It is about the decision a writer makes at each step: picture or no picture, and if a picture, which part, with what on it. Video, recordings and the production side of visuals belong to the Visual & Video Guides series, and this article leaves them there.

It covers when a screenshot earns its place and when text wins, then the screenshot that is only decoration. Cropping to the thing that matters and one annotation and only one follow. Next come the rule to never use real data and the screenshot that goes stale. A short war story and the screenshot checklist to copy follow, in that order.

When a Screenshot Earns Its Place

A screenshot earns its place when it answers a question that words answer badly, and there are three such questions. Where is it? A control on an unfamiliar screen, among forty others, is found faster from a picture than from words. The words might be "at the top right, below the search box, to the left of the gear icon". What should I be seeing? A result might be a shape or a colour rather than a word, such as a green bar or a particular layout. That result is confirmed faster by comparison than by description. And what does that thing look like? An icon with no label, a symbol, a particular kind of warning, cannot be named in a step because the screen does not name it either. Those three are the whole case for screenshots. Everything else is text.

Text wins everywhere else, and it wins for reasons that matter more than they seem. Text is searchable, so a reader who types the label on their screen finds the article; a label in a picture is invisible to search. Text is copyable, so an address or a setting can be pasted rather than retyped from a picture. Text updates in seconds when a label changes; a picture has to be retaken. Text reads on a phone held in one hand at two in the morning, and a shrunk window does not. And text is read aloud by the software that blind readers use, where a picture is a silence unless someone wrote the alternative. The Reader Who Cannot Watch covers that reader. The short version is that the step must be complete without the picture.

So the default is no picture, and a screenshot has to argue its way in at each step. The table below is the argument, settled in advance for the common cases. The pattern is that a picture belongs where the reader has to recognise rather than read, and does not belong where the reader has to do, type, or check a word. The honest result of applying it to most articles is one or two screenshots, not fourteen.

The Screenshot That Is Only Decoration

The most common screenshot in any knowledge base shows the reader what the text just told them, at a size where they cannot read it. It comes after a step they did not need help with. It is the picture of the sign-in page. It is the whole window after "Click Settings", with the Settings page in it. It is the confirmation dialog, shown in full, so that the reader can see the word "OK" they were told to click. Each one was added because a picture felt thorough. Each one costs the reader a scroll, the phone a download, and the editor a retake when the screen changes. A knowledge base with a picture after every step is not well illustrated. It is a slideshow with captions.

The costs are not abstract. Grace's fourteen screenshots pushed each step a full screen away from the next. Following the article meant scrolling past a picture to find the next line of text, losing the place, and scrolling back. On the practice tablet, each full-window image was shrunk to the width of the page. The text in it was unreadable at any zoom that still showed the whole thing. And when the practice system changed its menu layout the following spring, all fourteen were wrong at once. That is fourteen retakes or an article that lies in fourteen places. Four of those pictures earned their place. Ten were there because the writer had a screenshot tool and a feeling that more was better.

The test for a decorative screenshot is to delete it and read the step. If the step still tells the reader exactly where to look and what they will see, the picture was decoration. If the step has lost something, work out what. If it lost a position on an unfamiliar screen, the picture stays, cropped. If it lost a word, the word goes into the text and the picture still goes. I have deleted about two in every three screenshots from every knowledge base I have ever been asked to tidy. Nobody has ever asked for one back. (They did ask why the articles had got shorter, and seemed pleased.)

Crop to the Thing That Matters

A screenshot shows one thing. The frame is drawn tightly around that thing plus just enough of its surroundings for the reader to find it on their own screen. For a tick box in a form, that is the tick box, its label, and the one or two fields above and below it. That lets the reader see which part of the form it is in. For a button in a toolbar, it is the toolbar. It is never the whole window, because the whole window shrunk to the width of an article is a picture of a window. The reader already has one of those. Grace's "Out of hours" tick box could have been cropped to the tick box and its three neighbours. It would have been readable at the size of a business card and found on her screen in a second.

Keep the picture at the size it was taken, or close to it. That keeps the text in it the same size as the text on the reader's screen. A crop that shows the control at real size does not need the reader to zoom. A crop that needs zooming has been cropped too loosely. The usual sign is width: a crop that is as wide as the article is almost always showing too much. If the thing that matters is small and far from anything the reader could use as a landmark, take two crops. In that case, take one wide to show the region and one tight to show the control. That is better than one picture that fails at both jobs.

Crop before saving the image, not in the article editor. An image that is cropped by the editor is often the full window underneath, with everything that was on it still in the file. That matters for the section on sensitive data below. It also means the file is the size of the full window and loads like one. Crop in the capture tool and save the crop. Name the file after the article and the step so the editor can find it when the screen changes. Put it in the article beside the step it belongs to, not in a gallery at the end. A picture that is not beside its step is a picture the reader has to go looking for, which defeats the purpose of having one.

One Annotation, and Only One

An annotation is a mark drawn on the screenshot: a box, an arrow, a circle, a number. Picture a cropped screenshot of a form region with one box around the tick box the step says to tick. It is the most useful picture in the knowledge base. The same crop with four arrows, two boxes and a numbered list of callouts is a puzzle. The reader's question at a step is "where is the one thing I act on now?" The annotation answers it by pointing at one thing. If the picture needs to point at two, the step is two steps, and each gets its own crop or the same crop with a different single mark.

The mark goes around the control, not over it, so the reader can still see the label they are matching. Use the same mark, the same colour and the same weight in every picture in the knowledge base. That lets the reader's eye learn to find it without thinking. The style card that fixes those choices across a knowledge base is covered elsewhere. So is the use of numbers when a single picture genuinely has to show a sequence. Both belong to Annotated Screenshots Done Well. The writer's rule, inside one article, is simpler: one picture, one mark, and the mark is on the thing the step says.

Do not use the annotation to say what the text should say. An arrow with "click here" written beside it is a step that has moved into the picture, where search cannot find it and a screen reader cannot speak it. The step says "Tick the box labelled Out of hours". The picture shows a box around that tick box. The caption under the picture says what the picture is of, in one line: "The Out of hours tick box, below the admission time." Three places, three jobs, nothing said twice and nothing said only in the picture.

Never Real Data

A screenshot is a photograph of a real screen, and a real screen has real data on it. There is a real person's name in the account field, a real e-mail address in the mailbox, and a real customer in the record. There are real ticket subjects in the list behind the dialog, and a real salary in the row the writer did not notice. The article is then published, and every reader of it can read that data at leisure. For a public article, that means everyone with access to the portal and sometimes everyone on the internet. The writer did not mean to publish it. The writer was looking at the tick box.

The rule is that every screenshot is taken on a test account with made-up data. Where that is not possible, the real data is removed before the image is saved. Removal means covering with a solid block, not blurring, because blurred text can often be read and sometimes recovered. It means removing from the image file, not drawing a box in the editor over a file that still contains the original underneath. Then look again at the parts of the picture that were not the point. Check the window title, which often contains the user's name, and the browser tabs, which contain whatever else the writer had open. Check the address bar and the taskbar. Check the notification that arrived while the capture was taken, and the list of recent items in the menu. The thing that matters was checked. The leak is always in the part that was not.

The rule applies to internal articles as much as public ones. Most knowledge bases let an article be visible to agents only or to everyone, and QuerySolv's does. The agents-only article may legitimately show internal screens that a user should never see. But a technician's screenshot of a real customer record is still a real customer record. The audience being smaller does not change what it is. The wider question of what must never appear in a document users can read, from admin paths to internal names, is the subject of What Must Never Be in the User Document. The screenshot is simply the way most of those things get in by accident.

The Screenshot That Goes Stale

Screens change, and the screenshot does not know. The button that was green is now blue; the tab that was second is now under a menu. The whole layout moved in an update nobody told the desk about. The text of the step can be fixed in ten seconds by whoever notices. The picture has to be retaken, cropped, annotated, checked for data and uploaded. So it is not fixed, and the article now shows the reader a screen that is not theirs. A stale screenshot is worse than none, because it tells the reader with great confidence that they are in the wrong place. They are in the right place. The article is in the past.

Three habits keep this manageable, and the first is the one this whole article has been making: fewer pictures. An article with two screenshots has two things to retake; an article with fourteen will not be retaken at all. The second is tight cropping. A crop of one control and its label often survives a redesign that moves everything else on the screen. A full-window shot goes stale the moment anything changes. The third is naming: a file called "admission-step9-outofhours.png" can be found and replaced by someone who was not the writer, where "screenshot-final-2.png" cannot. A system change should trigger a check of every article that shows that system. The register that makes that possible, with the versioning and the review trigger, belongs to Keeping Media Current.

Write the step so that the picture is a confirmation, not the instruction, and the stale picture does less damage. "Tick the box labelled Out of hours, below the admission time" is still right after a redesign that moves the box. A reader who sees the right label in the wrong place will trust the words. If the words had been "tick the box shown below", the reader would have had nothing to trust. The text is the article. The picture is a helpful stranger pointing, and strangers are sometimes out of date.

A Short War Story: The Mailbox Screenshot at Meridian Parts

At Meridian Parts, a technician called Jonas wrote "How do I set up an automatic reply when I am away?" He wrote it while sitting with the finance director, who had asked him to set hers up. He took the screenshots on her screen because it was open, cropped nothing, and published the article to the whole company that afternoon. Screenshot 2 showed her mailbox behind the settings window, with eleven subject lines readable at a squint. Those included "Project Kestrel: revised offer, do not forward", three supplier names in a dispute, and a line about a named colleague's capability review. A sales rep noticed it on day eleven and mentioned it, to his credit, to the desk rather than to anyone else. The article came down in a minute. The next two days went on Jonas and his lead opening every one of the knowledge base's hundred and forty images. Checking what else was in the margins found four more. The finance director spent an hour with the legal team deciding whether anything needed to be disclosed. That time, it did not. The cost was two technician-days, one legal hour, and a finance director who now asks what a screenshot is for before anyone takes one on her machine. The tick box in the picture had been perfectly chosen; the leak was in the part of the picture nobody was looking at.

The Screenshot Checklist

The checklist below is run once per picture, before the article goes to the editor. It is run once more by the editor, who will find the thing in the margin that the writer did not. Its first section is the decision to have a picture at all, and most pictures should fail it. The sections after that apply only to the ones that survive. Keep it short in use: a picture that passes takes a minute to check. A picture that takes longer than that is usually one that should have been cropped tighter or not taken.

SCREENSHOT CHECKLIST — ONE PER PICTURE
Article: ________________________________   Step: ____   File: ____________________

DOES IT EARN ITS PLACE?
  [ ] It answers "where is it?", "what should I see?" or "what does it look like?"
  [ ] Deleting it would lose the reader something the text cannot give.
  [ ] The step is complete without it (the text names the control and the result).
  [ ] It is not the sign-in page, the whole window, or a dialog with only OK on it.
  If any box above is empty, remove the picture and stop here.

CROP
  [ ] Shows one thing plus enough around it to find it on a real screen.
  [ ] Text in the picture is the size of text on the reader's screen (no zoom needed).
  [ ] Not as wide as the article. If it is, crop tighter or take two crops.
  [ ] Cropped in the capture tool and saved cropped, not cropped in the editor.

ANNOTATION
  [ ] One mark, around (not over) the control the step names.
  [ ] Same mark, colour and weight as every other picture in the knowledge base.
  [ ] No words drawn in the picture; the instruction is in the step, the caption says
      what the picture shows.

DATA
  [ ] Taken on a test account with made-up data, or
  [ ] Real data covered with solid blocks in the image file before saving.
  [ ] Checked: window title, browser tabs, address bar, taskbar, notifications,
      recent-items lists, the list or record behind the dialog.
  [ ] Nothing in the frame identifies a real person, customer, patient or deal.

STALENESS
  [ ] File named for the article, the step and the control: ______________________
  [ ] Caption written: ___________________________________________________________
  [ ] Alternative text written for a reader who cannot see it: ____________________
  [ ] Listed against the system it shows, so a change to that system triggers a retake.

Checked by writer: ________   Checked by editor: ________

Grace's admission article was rewritten the following week by the practice manager and the on-call nurse together. They went through the fourteen screenshots with the first section of the checklist and kept two. One was a crop of the admission form's right-hand column, boxed around the "Out of hours" tick box. The other was a crop of the green "Admission saved" bar that the reader should see at the end. The article lost twelve pictures and about four screens of scrolling, and gained a result line after every step. The next out-of-hours admission was recorded at 03:40 by a locum who had never seen the system, from a tablet, without a call. The two pictures that stayed were the two that pointed at something.

Frequently Asked Questions