When does your documentation need screenshots?

No readers like this yet.
What makes a new medium successful?

Opensource.com

One of the common questions when developing documentation is, "How many screenshots should I include?" Answers range from "None!" to "All the screens!" A picture may be worth a thousand words, but screenshots are often used as a crutch for poor documentation or poor design. The best answer is to use them when you need them, and don't use them when you don't. So how do you know when you need them?

Illustrating hard to explain concepts

If your interface is radically different from what a user might be used to (or if it's too cluttered or otherwise not great), that's a good indication that you should include some screenshots. If you can't find the words to clearly explain what you want the reader to do, a screenshot may be a good bandaid while you improve the interface. The key here is what you want the reader to do. Generally, you don't need to include screenshots for UI elements that the user doesn't really interact with.

What's your audience's skill level?

Of course, the audience is an important consideration. If the reader has used a GUI-based desktop before, you don't need to explain the "File -> Print" menu. If you're writing for complete neophytes, then maybe it's a good idea. Similarly, if the reader is an experienced user, you don't need to screenshot each pop-up dialog. "Error: file not found" and "Error: could not write to file" are not dissimilar enough to require a graphical explanation, especially if the only action for both is to click the the "OK" button.

An example of good use of a screenshot from Slack; highlights a specific area of the user interface that new users may not be familiar with.

Less is more

"But what's the harm in including screen shots?" you ask. There are four main reasons. The first is that they need to be changed every time your UI changes, otherwise they become out of date and your readers get confused. This is extra effort.

The second is that if the UI you're writing about is skinnable or otherwise configurable, the person who makes the screenshots might have a different layout than the default, which will again confuse the reader. (Note that "we'll just use the default configuration to make screenshots" isn't necessarily a good answer, since downstream may change defaults.)

The third reason is that screenshots can't be translated. If your documentation is translated into multiple languages (and really, don't you hope that your project becomes popular enough that multiple languages becomes a requirement?), your translators will have to reproduce the screen shots in the target language. Otherwise, your translated documents become second-class citizens.

Lastly, and arguably most importantly, screenshots are bad for accessibility. Sight-impaired users rely on text-to-speech to read your documentation. Screenshots are not conducive to screen readers, so you'll need to write good text anyway.

Screenshots are not a crutch

"But the screenshots add some nice visual flair and they help break up the wall of text!" Your argument does not convince me. Well-laid-out content breaks up walls of text, too. Unless you're publishing plain text, your markup language of choice can probably use some kind of style, CSS or otherwise, that helps the visual appeal. The For Dummies series of books is some of my favorite documentation and most of the books use minimal screenshots. Frequent callouts and section headings break up the text.

When you're writing your documentation, try to do it without screenshots. Describe what the reader should do or what they see. When you simply can't explain what's going on, add the screenshots you need. A write-first mentality will make your writing better over time.

Doc
Dish


This article is part of the Doc Dish column coordinated by Rikki Endsley. To contribute to this column, submit your story idea or contact us.

User profile image.
Ben Cotton is a meteorologist by training, but weather makes a great hobby. Ben works as the Fedora Program Manager at Red Hat. He is the author of Program Management for Open Source Projects. Find him on Twitter (@FunnelFiasco) or at FunnelFiasco.com.

3 Comments

I appreciate your article, Ben. I will try to remember this when I write my next article! ;-)

Although there are some good points here, I have to as a whole disagree.
It may be somewhat dependent on the software the documentation is for, but for Scribus, a desktop layout program, judicious use of some screenshots is as close to essential as I can imagine.
One important thing is not to take a screenshot and then stick it in the documentation unedited. There are various way to highlight or draw the visual attention to the point(s) of interest.
One thing about screenshots is that once you are somewhat familiar with what dialog looks like, it's easy enough to just skip over the picture and focus on the text.
Sometimes a screenshot may actually help you write the text you need to explain something. In that case, it's entirely possible that you may later decide the screenshot is no longer needed.
The argument of needing to redo screenshots as the software changes is a bit thin. Those who will not redo screenshots as needed are probably not going to rewrite their text either. Documentation is a living, breathing thing that needs to be cared for like the plants in your garden: fertilized, trimmed, watered, and at times replaced.

Greg, thanks for reading. You're absolutely right when you say "judicious" use of screenshots. I didn't advocate against ever using screenshot but only when they're necessary, which is generally less often than people think.

I also agree that documentation needs to be continuously curated. Indeed, that's probably the single largest problem with open source documentation. But screenshots are more work than updating text, and I've seen text get updated without corresponding screenshot updates. In any case, the increased burden on translators is not trivial.

In all, I'd much rather see documentation with lots of screenshots than no documentation at all. The use use of screenshots should be a conscious decision because it adds to the document, not a reflexive action.

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.