Screenshots in documentation

I’ve spent a lot of time at work lately writing documentation or getting others’ drafts into our preferred format. I’ve written and consumed technical documentation quite a bit over the years, so it’s no surprise that I have a few opinions on the matter. One of my opinions is that screenshots are often used as a crutch to support poorly-written docs.

I shared this thought and got a little bit of pushback, so I thought it was worth expanding on. I’m not opposed to screenshots. In fact, I’m quite in favor of the judicious use of screenshots (if for no other reason that sometimes it’s nice to break up the wall-of-text). But showing the same window with and without text entered into a text box is excessive.

Pictures may be worth a thousand words, but they have a lot of downsides. Well-written documentation can be followed without a picture, which is very important for the visually-impaired who rely on text-to-speech tools. Text strings are much easier for translators to handle. That’s not important for all documentation, but can be very important if you have (or want!) international customers or contributors. Images are also less awesome in version control systems (which you’re totally using, right?)

A friend asked how I felt about videos. If they’re used in concert with text-based documentation, I prefer them to static images. Videos can provide visualĀ and audio cues, which help accessibility. Videos also more obviously show how to manage complex interactions. Of course, the question that arises from this is: if your interactions are so complex as to require video explanation, do you need to fix your UI/UX?

The target audience matters, too. Technical users require fewer visual aids than unsophisticated users. When you write your documentation, use as many screenshots as you need, but no more than that.

3 thoughts on “Screenshots in documentation

  1. Pingback: When does your documentation need screen shots? | Blog Fiasco

  2. I’d agree that documentation which is just a series of screenshots isn’t particularly helpful (though given a choice between that and no documentation at all I’d definitely prefer to have *something*). Screen captures do have a number of purposes, beyond “do what’s on the screen”. They provide an anchor which can be used to confirm progress through a series of steps, for example, or a summary of settings at the end of a process (e.g. Wizard). There’s also a subtle “this has *actually* been done and here’s the evidence” aspect. In any case, screenshots [*] need to be compliments with a good written commentary.

    [*] this includes TTY captures/confit snippets – using a fixed pitch font of course!

Leave a Reply

Your email address will not be published. Required fields are marked *