I'm Mike Pope. I live in the Seattle area. I've been a technical writer and editor for over 30 years. I'm interested in software, language, music, movies, books, motorcycles, travel, and ... well, lots of stuff.

Read more ...

Blog Search

(Supports AND)

Google Ads


Subscribe to the RSS feed for this blog.

See this post for info on full versus truncated feeds.


When it comes to .NET, if you think something is impossible you are probably thinking too hard.

"Doc Detective"


<May 2022>



Contact Me

Email me

Blog Statistics

First entry - 6/27/2003
Most recent entry - 4/10/2022

Posts - 2640
Comments - 2648
Hits - 2,472,667

Entries/day - 0.38
Comments/entry - 1.00
Hits/day - 358

Updated every 30 minutes. Last: 12:16 PM Pacific

  09:38 PM

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. [^]

[categories]   ,