When we talk to users about software documentation, we consistently get feedback that they like having
screenshots in the docs. But screenshots are a conundrum for a technical writer because
they introduce issues for the writer—issues that don't necessarily affect any one reader, but that can reduce
the quality of the user experience over time and that have other meta implications. In fact, I'd say that
screenshots are a documentation feature where the interests of the reader and writer can be quite at odds, as
I'll explain.
Pros of screenshots
You probably know the advantages of including screenshots in documentation, but let's review. Screenshots have
the following benefits:
Orientation. A screenshot can help the reader understand the layout of a console or window that’s in
front of them.
Compact information. This is the "picture is worth a thousand words" benefit—a screenshot can save
the reader from having to read a lot of words. For example, a screenshot can show a computer form with all
the values already filled in that the writer otherwise has to describe in text.
Signposting. A screenshot can reassure the reader that they've done something correctly—"when you're
done, it looks like this." A corollary is that if the user isn't seeing the thing you're
picturing, they know that something went awry. (I've written elsewhere about signposting in documentation.)
Chunking /graphical relief. Readers hate "walls of text," meaning long blocks of uninterrupted words.
One of the ways that you break up (that is, chunk) text or long procedures is to include graphics.
Procedures that include screenshots feel friendlier to readers.
Cons of screenshots
The benefits of screenshots are clear enough that many authors use screenshots enthusiastically. I've seen
procedures where every step included a screenshot. However, the following downsides to screenshots are often not immediately apparent:
-
Time and resources. When you're working on software documentation, getting a computer system
into the proper state where you can snap the correct image takes time. Then there might be additional tasks
like adding image files to your content management system, writing alt text, and staging all the screenshots
and checking them.
Sure, it's all part of the documentation process, but it's added friction. The more screenshots, the more friction.
-
Space in the document. If you're working on paper-based or PDF-based docs, adding screenshots adds
pages to the docs. If you have space or size constraints, this can be an issue. (For the most part, this isn't an
issue for web-based documentation.)
Rendering differences. A screenshot might look fine when you're testing a procedure in a browser
window on your 24-inch monitor. But users might be using different form factors. Can users still
get the benefit of the screenshot if they're looking at it on a smaller monitor, or on a tablet, or even on
a phone?
-
Maintenance. As we know, computer UIs change, sometimes frequently. But a screenshot has to
reflect the UI that the reader is seeing when they're reading, which might be months after you wrote the procedure and
snapped the screenshots. Adding a screenshot means you've given yourself a big ol' maintenance task, because
…
A screenshot that's wrong is worse than no screenshot at all.
Remember orientation and reassurance from the "Pros" list? An incorrect screenshot disorients and
un-assures the reader. It significantly degrades the user's experience and their perception of the
document. (This is not just speculation; users tell us this.)
To add to the issue, there's the burden of re-creating a screenshot to reflect an updated UI. The work that you
had to do to create it in the first place you have to do all over again for a new version of that screenshot.
-
Searachability. Any text that's inside a screenshot probably isn't searchable. If you take a
screenshot of a computer form, the labels and values shown in that screenshot will not be indexed for
search.
-
Accessibility. Screenshots are not going to be visible to some part of your audience. If someone is
using assistive technology like a screen reader, the screenshot is effectively opaque.
-
Translatability. If your documentation is translated, you need to think about how screenshots will
work in translation. Do the screenshots reflect the UI that someone sees who's using a
translated version of your product?
If your localization process doesn't include translating screenshots, are you okay with
non-English readers seeing a graphic that doesn't reflect their UI? If the screenshots are going to be
translated, who's snapping the screenshots in localized versions of your product and adding those screenshots to
the localized docs?
Even if you don't have a translation pipeline, it's worth thinking about whether non-English speakers might
consume your documentation using machine translation and how screenshots then work for those readers.
Advice for using screenshots
So: users like screenshots, but they can be trouble for writers. I've worked in environments where the default
approach was no screenshots, for the reasons stated. How can we reconcile the pros and cons? Here are some
suggestions:
-
Think about the doc type and audience. Screenshots are more useful in tutorials and quickstarts
than in other types of docs. If the document is for someone who's
experienced with your product (and you have made this clear in the doc intro, right?), they might already be
familiar with its interface and don’t need as much orientation, reassurance, and signposting as someone new to the product.
-
Use screenshots judiciously. As you work through a procedure or if you're studying users who are
doing that, pay attention to where there are hitches and snags. Use text to guide users through these
(more on that in a sec), but note those hitches as places where a screenshot might help. Definitely
don't add screenshots only to make a procedure friendlier-looking.
Obviously, if the interface is so complex that it's difficult to use without visual guidance in the docs,
that's a problem for all users. In that case, while you're using documentation to work around issues in
the product design, file all the bugs you can about these flaws.
-
Don’t rely on pictures alone to convey information. Even if a screenshot can theoretically
replace a lot of text, in practice, it shouldn't. Accessibility requirements mean that if you show a
filled-in form as a screenshot, you should also describe the form fields and their values in text.
The same applies for any document that's going to be translated.
For all contexts, the writer also has the curse of knowledge: they know why they took the screenshot
and what it's intended to convey. But that isn't necessarily clear to readers, so they still need
explanations of what the screenshots shows. A screenshot should enhance the writing, it should not
replace it.
-
Focus on the relevant information. Crop to the part of the screenshot that you want users to
see. This helps users focus on what you're trying to show them. It's also possible that cropping can future-proof the screenshot somewhat—if there are
changes to the UI, perhaps the small part of the UI that's shown by a cropped screenshot might not need to be updated.
-
Have a maintenance plan. Whenever you snap a screenshot, anticipate as best you can what
the UI will look like in a year or two. Create a documentation maintenance plan and include a task
to re-run procedures and make sure that all the screenshots are accurate. To put it another way,
screenshots are another checklist item in your doc debt, so plan accordingly.[1]
As I say, screenshots are a feature of the docs where readers and writers have different interests. Doc
decisions should not put greater weight on what's convenient for the writer versus what's useful for the
reader. But we also need to take into account the larger picture of user benefits—accessibility,
translation, and the degraded experience that incorrect or out-of-date screenshots provide.
As with other features of the documentation, deciding to use screenshots requires us to take a long view of the content we're creating and how we can best benefit our readers (all of them) for now and in the future.
[1] You really, really learn
to appreciate restraint in using screenshots after a big UI change where you had to update 40 or 60 or
100 screenshots in a doc set. [^]
|
