Wednesday, October 07, 2009

Screen Shots in Documentation

Sometimes someone gives me documentation that "so and so" put together for his IT group that tells them how to install our product. Generally, the purpose is to show me how "real users" want to see documentation. Invariably it is a 32-step procedure with a screen shot in every step.

Well, obviously, the writer in not familiar with Robert Horn or the demands for accessibility and globalization that I must deal with, so I have dismissed it.

But it just keeps coming back, so I'm going to ask myself, "What if they're right?"

First, so I can be more open to new thinking, let me purge myself of all the reasons I have traditionally rejected screen shots in documentation:
  1. Every time the UI gets modified, screen shots must get updated.
  2. Every time the UI gets translated, new screen shots must be generated in the new language and coordinated into the translated text.
  3. Information in the screen shot (like button selection or entries) must be documented in the steps anyway so the information can be rendered by adaptive technologies like screen readers.
  4. Many screen shots just show the reader what the user is already seeing.
  5. Users may be overly attracted to the visual and miss important points in the explanatory text.
  6. It makes the document bigger.
Now let me changes hats a bit a take a critical look at my traditional positions.

Objection 1 (updating screen shots) seems writer-centric. Essentially it is saying "It makes my job harder." Well if it does make the user's job easier, it would make sense that it makes my job harder--nothing's free. OK, Objection 1 is bad.

Objection 2 (translation) is just an instantiation of Objection 1. Therefore, Objection 2 is bad.

Hmmmm, I don't like how this is going so far :-(

Objection 3 (information still has to exist in words) has some substance. Information in a screen shot cannot be used to substitute for information in the steps. Unless of course, you're not worried about accessibility. Now that's an entirely different blog!

Objection 4 (what good is a picture of what the user can clearly see) has always resonated with me. Here is an example:

This example is particularly problematic for me since the UI text is actually pretty explanatory.

It also can get fairly tedious. consider the next steps that follow the example above:

But it seems that this by-the-numbers, picture-by-picture aspect is the attraction for this type of documentation. As in "So easy a..." well you get the picture.

So am I hearing from users who want this type of documentation, or am I hearing from technicians who think users need this level of hand-holding?

Objection 5 (visually distracts from useful text) has merit. Although it's true that a picture is worth a thousand words, it did take seven words to express that concept, and I'm not sure how you would get that across as well in a picture. Also, I think it is easier to wrap context around an example if the example is in words. For example, in the following shot, is the value 10240 an example or is it the value the user should enter?

And in the next example, the screen shot visually contradicts the step.

Objection 6 (document size) should be evaluated based on the merit of the document. If the screen shots make the document better, no one will care about bigger.

So where does this leave me?

I am going to be more open to including screen shots where they do the following:
  • Help reassure the user that where they are in the UI is the right place to be
  • Help call attention to a specific area of a complex UI
  • Support an example that is hard to visualize otherwise, e.g., setting up a desktop configuration
So where they add value, I'll be more willing to tackle those aspects that make my job harder (e.g., documentation maintenance). But just as I would with words, I'll cut out the obvious and whatever does not add value. I prefer an additive approach (put it in only when the words seem inadequate) over a subtractive approach (take it out if it seems superfluous). In other words, I'll be more open to screen shots in the future, but they have to work themselves into the document, not just be their by entitlement until expelled.


Unknown said...

I think that another aspect of reassuring the users that they are where they expect to be that is not really related to the computer task documentation per se, is that they use the screen shots to return to where they were in the documentation (and task/procedure) after phone calls or other interruptions. In today's office environments, hardly anyone has the luxury of being left totally alone while they learn to use a new software tool or program.

malcontent said...

I agree they are useful, unfortunately more so when the UI is less obvious and you have to explain each field, the units expected, etc.

One trick I've learned when dealing with translations: If it's just a matter of explaining the general layout of the window, I've created wireframes colored appropriately, but with no words in them. This avoids the issue of taking a screenshot in every language.

I've also removed the version number from the title bar of setup screens so that I only have to change it if the controls on the screen have changed.

Michael Hughes said...

After jotting down my initial thoughts, it occurs to me that I often see this when someone is communicating how to set up for a very specific configuration. Then it is easier to communicate that through screen captures (make your dialogs look like these) than for documentation that has to be more general. So maybe my best response is "That's OK for a very tightly defined configuration and audience (and where accessibility or globalization are not issues), but the official documentation does not have that luxury."

MattBNH said...

Screenshots can be like crack. You don't need it, it can kill you, but you want it bad. Customers and reviewers who have gotten hooked on them in our books complain when even a dirt-stupid obvious screen shot is missing (they must want to see that progress bar frozen in time).
Wireframes, removing changeable version numbers, etc. are all good hints and alternatives.
If you want to see the type of situation where screenshots are necessary, try configuring SSL in IIS using one procedure for all operating systems with no pictures. There are just too many very complex settings with arcane navigation steps to do without pictures. Screen capture videos can be clearer and briefer for end users, but they are no less costly to update.

Suzette said...

Wouldn't it be nice if we could just have a standard answer? I think it just depends. It depends on the complexity of the task and UI, it depends on the experience level of the audience, and to some degree it depends on the maintenance required and priority it would receive during updates. Oh, and of course, accessibility may play a role too. While I'm on the it depends path, it also depends on the output.

For example, if the user is a beginning user or a user who does not sit at the computer all day, and the documentation is delivered via context-sensitive online help, we typically don't use screen shots. I like to use a rule of thumb that we should only use screen shots when they add value or clarify the steps that would be unclear without them. Of course, this is still largely subjective. We do output these to print such as User Guides, but not to quick references.

Michael Hughes said...

Thanks for the many fine comments so far. I think there can be an inherent laziness about screen shots in that they let us get away with a really glitzy way of saying "Check the Enabled box" without having to explain when, why, and when not.

Suzette said...

Your comments make me wonder whether usability studies have been conducted that compare and contrast the usability of instructions with and without screen shots.

Michael Hughes said...

Graduate students looking for a useful research project! Suzette has identified an excellent opportunity.

Michael said...

To me the "when, why, and when nots" are what distinguishes reference documentation from user documentation...the systems I've documented are often complex enough for basic tasks. It all depends on who the users are and what they are doing with it.

Michael Hughes said...

Maybe I'm reading you backwards, MichaelC. When, why, and when nots would NOT be in reference-that info is the core information that user assistance should deliver. To me, reference is more for how big, what's the syntax, etc. type of stuff. A reference book on Ireland would give me the area, population, and average temperatures. A travel guide (user's guide) would tell me when to go there and where for different interest areas.

Andrew Light said...

Great discussion. For a client some time ago, I tried a "please everyone" approach. At the beginning of a procedure's documentation, we did a text-only write-up. Advanced users appreciated the 1-page cut-and-dry. Then, we followed it up with the hand-holding section, complete with screen-shots and the like. This way, the reader can decide what they get based on what they need.

pumpkinslayer said...

In our computer hardware user manuals we used to include screenshots of every step in the installation process of the Windows Software drivers. That's the typical Windows installation of: Next, Next, Next, Finish.

Nothing unusual.

I came into the company after that had started and we created a process so we could capture and recreate the whole sequence in 3 hours.

Nevertheless, as a group we decided to just forgo the whole section and just explain that each item shown in the main menu must be installed.

Over a year later, no customer has complained (they're pretty liberal with complaints through our sales and support staff) and a single project manager asked, "Didn't we use to include those?"

The other benefit is that we've now cut about 5-10% off the document production time and can put those efforts into other areas that really do need better explanation.

mixed_metaphor said...

The point of documentation is not to describe the features of a product, the point is to help people use it.

Regarding your first two points, that creating screenshots uses resources, the objection you give assumes that one has the resources to do the screenshots. Time spent making screenshots is time spent not doing other potentially more useful stuff, like writing. Populating a document with screenshots without understanding their cost and value is just poor product management. Since many documentation writers don't take the time to understand what the user actually needs, they take the blunderbuss approach and "document everything", including every "Click OK" dialog.

What users want is meaty content. Putting in screenshots is saying "Let them eat fluff".

Are all screenshots bad? No. Should you spend time making / maintaining screenshots without understanding the cost / value relationship? No way!