Annotated Screenshots Done Well: One Highlight, No Secrets

Wednesday, 11:30, at Acme. Sunita started in accounts on Monday and has opened the knowledge base article "Submit an expense claim" for the first time. Under step three is a screenshot of the whole claims screen with seven red arrows, three boxes, and a yellow circle. There is also a block of handwritten-looking text in the margin saying "make sure this is filled in!!". She phones the desk. "Which arrow is step three?" Dan on the desk opens the article and cannot say either. The arrows are not steps; they are the places the author's eye went while taking the picture. He also notices a slice of the author's inbox along the right-hand edge of the screenshot. It shows a subject line beginning "Re: disciplinary". In the claim form's own fields, he notices a real supplier's name and a real amount. The article has been public to all staff for a year.

An annotation is a mark added to a screenshot that tells the reader where on the screen to look. It can be an arrow, a box, a number, or a block covering something private. An annotated screenshot done well has one highlight and uses the mark that suits the target. It has had every private detail removed in a way that cannot be undone. And it looks like every other screenshot in the knowledge base, so the reader learns the language once. This article is part of our Visual & Video Guides series, and it is about the mark, not the picture.

It covers what an annotation is for, then one highlight per image. Next come arrows, boxes and numbers, with a table of which suits which target. We cover cropping tight and showing context once, then redaction: what must never be in the frame and how to remove it. Next comes one style across the whole knowledge base, then the step text, caption and alt text that go with the image. We finish with the two-minute workflow, a short war story, and the annotation style card to copy, in that order.

What an Annotation Is For

The screenshot shows the screen, and the annotation says where on it to look. That is the division of labour, and most bad screenshots come from forgetting it. A screen has forty controls on it. Without a mark, the reader scans all forty looking for the one the step mentioned. That is the same work as not having a picture, with the added cost of a picture. With one mark, the reader's eye lands on one control and the step text tells them what to do with it. The mark directs the eye. It does not instruct; the text instructs.

Whether a screenshot belongs in the article at all is a separate question. It belongs to Screenshots That Help, and the Ones That Do Not, which is about the writing decision. This article begins after that decision is made: the step is hard, the reader is on an unfamiliar screen, and a picture is justified. Now someone has to draw on it. Drawing on it badly undoes the justification. A screenshot with seven arrows has democratically decided to point at everything. And the reader is back to scanning forty controls, now with arrows in the way.

The mark is also a promise about the text. If the step says "click Save" and the box is around Save, the reader trusts the next picture. If the step says "click Save" and the arrows point at Save, Cancel, the date field and the inbox, the reader stops trusting pictures in this knowledge base. They read only the text, which means every picture after that is maintenance with no benefit. One highlight, matched to the step, is how pictures earn the right to be looked at.

One Highlight per Image

The eye lands on one thing. Put two marks on an image and the reader looks between them, trying to work out which comes first. Put seven and they look at none. The rule is one highlight per image. When a step has two controls, the fix is two images. Or it is one image marking the first control with the step text naming the second. Most often, the fix is the discovery that the step is really two steps and should be split. That is the argument of one action per step in the writing series. The picture is where a two-action step gets found out.

The exception is the numbered sequence, and it is an exception only in appearance. A form with four fields to fill in order can carry one image with small numbered badges beside the fields, 1 to 4. The step text refers to them: "Enter the supplier (1), the date (2), the amount (3) and the cost centre (4)." That is one highlight system, a sequence, not four unrelated marks, and the reader reads it as one thing. Keep it to four or five numbers. Beyond that the form wants to be two images, or the step wants to be a table of fields in the text. The text can be searched and updated and the image cannot.

The highlight marks the control the reader acts on, not the result of acting. The reader needs to know where to click. What happens after the click is the next step's start state, and usually the next step's text describes it well enough. A second image showing the result is justified only when the reader cannot otherwise tell that the action worked. A confirmation that appears somewhere unexpected, say, would justify it. Then it is a second image with its own single highlight, not a second mark on the first.

Arrows, Boxes and Numbers: Which Mark for Which Target

The box is the default. A rectangle with a small margin around a button, a field or a panel encloses the target without covering it. The reader sees both the control and its edges. The arrow is for targets a box would hide: a tiny icon, a link inside a sentence, a single character in a status bar. It points from empty space, is short, and never crosses text. The number is for sequence, as above. Text written on the image is almost never right, because words on a picture cannot be searched, translated, read aloud or updated. They belong in the step beneath. The table below is the full set.

Pick the mark by the target, not by habit. Most people reach for the arrow because it feels like pointing. Most arrows in knowledge bases are pointing at things large enough to box. They point from a corner of the image, across three other controls, with a second arrow for luck. A box around a button is quieter, clearer, and does not require the reader to follow a line. Arrows are for the things boxes cannot do, which on most screens is one control in ten.

Crop Tight, Then Show Context Once

Crop the image to the dialog, the panel or the part of the window the step uses, with a little margin. That makes the control large on the page. The crop decides the text size: a whole screen shrunk into an article column is a thumbnail of a screen. The control the reader needs is a dot with a box around it. A dialog cropped to its own edges, at the same column width, has text the reader can read and a control they can recognise. Keep the window's title bar in the crop when it tells the reader which window they should be in; drop it when it does not.

The reader on an unfamiliar screen also needs to know where the dialog is. That is the one case for a whole-screen image, and it is shown once. The first screenshot in the article shows the whole screen with a single box around the region every later screenshot will be cropped to. And the step text says "the settings panel is on the left, boxed below". Every image after that is cropped to the panel. The reader has been told where the panel is once, in a picture, and is then shown the panel at a size they can read. Showing the whole screen every time, to be safe, makes every image unreadable to be safe.

Crop before annotating, not after. The crop changes where the mark goes and how big it should be. And a mark drawn on a full-screen image and then cropped is often the wrong weight for the crop. The whole-monitor screenshot, placed in an article column, is legible to nobody but the author, who remembers what it said. Crop it until a stranger could read the button's label.

Redaction: What Must Never Be in the Frame

A screenshot is a photograph of everything on the screen at that moment. And the list of things that must not be in it is long: people's names, e-mail addresses, phone numbers, customers' or patients' details, and real ticket numbers and subjects. The list also includes usernames, server names, internal addresses and paths, the taskbar with other applications showing, and the browser's other tabs and bookmarks. It includes the notification area, the desktop, and anything in a window partly visible behind the one you meant. The full list of what a user-facing document must never carry is in What Must Never Be in the User Document. And a screenshot is a user document in picture form.

Prevention costs less than cure. Take the screenshot from a test account on a clean window with notifications off, exactly as the recording set-up in Cheap Production That Looks Fine describes. Then there is nothing to redact, because nothing private was ever on the screen. Fill the test account's forms with plainly made-up values, a supplier called Example Supplier Ltd and an amount of 12.34. That way nobody, including a future auditor, has to wonder. Then crop tight, which removes the edges where the inbox lives.

Where something private is in the frame anyway, cover it with a solid, opaque block in the style-card colour. Never blur or pixelate. A blur can sometimes be reversed, and it always looks like a smudge on the lens. Worst of all it is easy to miss when checking, because it looks like a blurry bit of screen rather than a deliberate mark. A solid block is honest; it says "something was here and we removed it". Anyone checking the image sees at once that a redaction happened and can ask whether it was enough. Then check the edges and the corners, because that is where the background window and the taskbar are, and that is where nobody looks.

Which side of the knowledge base the article is on decides how much redaction is needed, so decide that first. A technician-only article about the admin console can show the console's hostname, because the people who can read the article can also log in to it. The same screenshot on the public side cannot. If you run QuerySolv, an article is visible either to agents only or to everyone. The screenshot inherits that from the article it sits in. So the first question before any redaction is which side of that line the article is on. The same is true in any tool with an internal and a public section: the picture's audience is the article's audience. I once published a screenshot of a settings page with my own browser's tab strip along the top. The tab strip listed, in order, the settings page, my bank and a recipe for soup. The soup got more comments than the article.

One Style Across the Whole Knowledge Base

Every screenshot in the knowledge base uses the same highlight colour, the same stroke weight, the same corner style, and the same badge shape and font for numbers. Every screenshot also uses the same block colour for redaction, the same crop margin and the same image width. The reason is that the reader learns the language once. If the box is amber in one article and red in the next, the reader wonders whether red means something different. It does not; it means a different technician took the picture. A consistent mark becomes invisible as a mark and visible only as a pointer, which is the whole aim.

Choose a highlight colour the interface itself does not use for meaning. Red is the colour most screens use for errors and most people reach for first. So a red box around a button looks, to a nervous reader, like the button is broken. Green is success in most interfaces and should be left to them. A strong colour that is otherwise rare on screens, and that is available in the screenshot tool everybody already has, is the right choice. And the specific choice matters less than everybody making the same one. Six technicians, six colours, and a knowledge base that looks like a ransom note.

Agree the style once, in ten minutes, write it on the style card at the end of this article, and pin it above the desk. The card settles colour, stroke, margins, badges, block colour, crop rule and image width. It names an owner, because a card with no owner drifts within a quarter as each new starter brings their own habits. When the card changes, the old images are not all redone. They are redone as their articles come up for review, which is the cycle described in Keeping Media Current When Screens Change. Consistency is a direction of travel, not a weekend.

The Step Text, the Caption and the Alt Text

The image never stands alone. The step above it says what to do, in words, completely: "Click Save at the bottom right of the form." The image shows where that is. A reader must be able to do the task from the text alone. That includes a reader with the images switched off, or who cannot see them. It includes a reader on a phone where the picture has collapsed to a stamp. The test is to hide the images and follow the article. If a step cannot be followed without its picture, the step is incomplete, and the picture is carrying words it should not be carrying.

A caption is optional and short: what the picture shows, in a line, when the step text has not already said so. "The expense form, with Save boxed." Alt text is not optional. It is one sentence that describes what is in the image and where the mark is, written for a reader who cannot see it: "The expense claim form; the Save button, at the bottom right, is boxed." It is not "screenshot" and it is not "image". How alt text is written and tested, with the rest of what the reader who cannot watch or see needs, is in Accessibility: The Reader Who Cannot Watch. Here the rule is that every image has it, and that it names the highlighted control.

Never put the instruction only in the image. Text drawn on a picture cannot be found by search, cannot be read aloud, cannot be translated, and cannot be copied. It cannot be fixed when the button is renamed without re-shooting the picture. "Make sure this is filled in!!" in the margin of Sunita's screenshot was an instruction that lived nowhere else. When the form changed it went on insisting, from inside a picture, about a field that no longer existed.

The Two-Minute Workflow

A good annotated screenshot takes about two minutes once the style is agreed, and the workflow is the same every time. Capture the window or a region with the screenshot tool that ships with the operating system, from the test account, in the start state of the step. Crop to the dialog with the card's margin. Draw one mark from the card, a box unless the target is tiny. Cover anything private with a solid block, and look at the edges. Save with the file name convention, the task and the step and a version number, so that the register in the keeping-current article can find it. Write the alt text. Place it immediately after the step text it illustrates, never before, because the reader reads the step and then looks for where.

If it is taking ten minutes, the image is doing too much. Usually it has three marks that want to be three images. Or it has a region that should have been a tighter crop, or an instruction being lettered onto the picture that belongs in the text. Usually, too, it was taken from a real account and is now being redacted block by block, which is twenty seconds of prevention becoming eight minutes of cure. Go back to the test account and take it again.

Keep the clean, unannotated capture beside the annotated one when it came from the test account. Then, when the style card changes or the mark turns out to be in the wrong place, the picture can be re-marked without being re-taken. Do not keep clean captures that contained anything private. A redacted image whose original is in the next folder is a redaction that has not happened. The script sheet and the clean capture are the sources. The annotated image is the output, and outputs are cheap to regenerate from sources and expensive to recreate from nothing.

A Short War Story: The Background Window at Stonebridge Insurance

At Stonebridge Insurance, a technician called Hamid wrote "Raise a claim payment" for the staff knowledge base. He took the screenshots from his own account, on his own monitor, with the claims system in one window and a customer's open file in another behind it. The crop was generous. Along the right-hand edge of the third screenshot, under a slice of the second window, a policyholder's name, postcode and claim amount were legible to anyone who looked. For five months nobody did, until Rosa from internal audit did. The incident report took a week. The review it triggered put three technicians through every one of the two hundred and twelve images in the knowledge base over the following week. Four more images turned up with a name, an address or a ticket subject at an edge. None of them were blurred, because nobody had noticed there was anything to blur. The desk rewrote its capture rule as "test account, tight crop, look at the edges", and put a highlight colour and a block colour on a card. It bound the review of images into the article review that already existed. The lesson Rosa wrote in the report was that a blur would not have saved any of the five. The problem was never that the secret was visible; it was that nobody had looked.

The Annotation Style Card

Fill in the card once, as a team, and pin it where screenshots get made. The blanks are deliberate: the values depend on which screenshot tool everybody has and how wide the knowledge base's article column is. And the right answer is whatever everyone will actually use. The card has an owner, who is the person a new starter asks and the person who changes it, rarely. Everything on it is a rule, not a suggestion, and none of it is a joke.

ANNOTATION STYLE CARD — ONE FOR THE WHOLE KNOWLEDGE BASE
Owner of this card: ______________    Last reviewed: ______________

CAPTURE
  Account: test account only, same permissions as the reader
  Theme: default (light) unless the organisation deploys another
  Window: one window, notifications off, no other tabs or windows visible
  Text zoom: ____ (text slightly too large on the author's screen)

CROP
  Crop to: the dialog or panel the step uses, plus ____ px margin
  Whole screen: once per article, first image only, with one box round the region
  Title bar: keep when it identifies the window; otherwise crop it out
  Image width in the article: ____ px; must be readable at phone width

MARKS (one highlight per image)
  Highlight colour: __________ (hex ______); not a colour the interface uses for errors or success
  Stroke weight: ____ px      Corners: [ ] square  [ ] rounded
  Default mark: box, ____ px margin around the control
  Arrow: only for targets too small to box; short; from empty space; never across text
  Numbered badge: filled circle ____ px, white bold digit, beside the control, max five per image,
                  referenced in the step text as (1), (2)
  Text on the image: none, except a one-word tag to tell two identical controls apart

REDACTION
  Block colour: __________ (hex ______); solid and opaque
  Never: blur, pixelate, or leave the original of a redacted image beside it
  Always check: edges, corners, taskbar, tab strip, notification area, background windows

TEXT THAT GOES WITH THE IMAGE
  Step text above the image says the complete action in words
  Caption (optional): one line, what is shown
  Alt text (required): one sentence; what the image shows and which control is marked

FILES
  Name: task-words-stepN-position-vN
  Keep: the clean capture beside the marked image, test-account captures only
  Store: beside the article in the knowledge base; register entry updated

Sunita's article now has three screenshots, one per hard step, each with a single box in the same colour. They were taken from a test account whose only supplier is Example Supplier Ltd. Dan re-took them in half an hour, most of which was spent finding a test account that could see the claims form. The handwritten "make sure this is filled in!!" became a sentence in step four. There it can be read by search engines, screen readers and new starters, and it will be deleted in a minute when the field goes.

Frequently Asked Questions