Should user documentation include screenshots?

Question

This question focuses on user documentation, not on code documentation.

I just finished my software project, and the people I work for are expecting me to write user documentation, describing everything the software does.

All the documentation they had until now (about the rest of the software they use) is full of screenshots, and sometimes barely contains any text. I think it's awful. I've been struggling for hours to understand how screenshots were connected, and most of the time I had to ask for help from someone else.

I wrote a Java desktop application, and its appearance is likely to depend on the current Windows theme and Java update. I don't think screenshots can form reliable, definitive reference.

Taking hundreds of screenshots and annotating them will take forever, and I don't believe it will help more than accurate, plain text documentation.

How should I approach putting the user documentation together? What guidelines should I follow regarding the use of screenshots versus explaining in text with user documentation?

nearly every how-to manual contained screenshots or was very well designed so users can find the referenced GUI elements easily, pick your poison — ratchet freak, Sep 16 '13 at 13:23
`its appearance is likely to depend on the current Windows theme` - use the default theme. with Aero switched off, it looks roughly the same for Windows Vista/7/8 — Konrad Morawski, Sep 16 '13 at 13:24
@KonradMorawski Indeed, but window decorations will still depend on the chosen theme (even if it doesn't make screenshots unusable, of course). — Aeronth, Sep 16 '13 at 13:30
@JeffO Judging by their previous documentation, they don't seem to know what they need. But it's only my point of view. — Aeronth, Sep 16 '13 at 14:40
It sounds to me developers of the other apps did just exactly what was asked: show everything the software does. Hardly useful, but then again, you shouldn't ask a developer to produce _user_ documentation anyway. The mind models of the writer and the reader are just too different. Last Saturday I worked on my brother's Mac and asked "what is the keyboard shortcut to get to the beginning of the line?" He said he didn't know. Frankly he didn't even know what a keyboard shortcut is. Turns out he always uses the mouse to get to the beginning of a line. And that would never have occurred to me... — Marjan Venema, Sep 16 '13 at 15:12
If you include screenshots, you need to keep the docs up to date with UI changes. Few things are more frustrating, even to my technical sensibilities, than a detailed, step by step, walk through of a process that tells me to click on buttons that no longer exist. — Sean McSomething, Sep 16 '13 at 16:38

score 13 · Accepted Answer · answered Sep 16 '13 at 13:50

13

Screenshots are an important aspect of the user guidance. However, they also need to be accompanied by clear and precise instructions. For example, having a screenshot showing the screen, a red arrow pointing to a button and the text reading 'Now that you have entered the filename, Click the Next button.' is much clearer than either the text or the screenshot alone.

Doing good click by click guides is time consuming, but worth it when it comes to supporting end users (even technical ones)

answered Sep 16 '13 at 13:50

Michael Shaw

9,915
1
23
36

I don't think click-by-click screenshots are necessary, but screenshots with arrows or other highlights to call out what's being discussed are a really good idea. – Bobson Sep 16 '13 at 14:04
If you are likely to either have to follow the instructions in 18 months time, after not having worked on this part of your product, or have to support more than a few end users, then putting in time and effort up front, when you can plan for it, rather than having to put in a similar amount of effort at unplanned times when you have an irate customer on the phone is a good trade off. 18 months later you will be glad of all the extra information – Michael Shaw Sep 16 '13 at 14:23
I was more thinking that one screenshot could cover multiple clicks, rather than each click getting its own image. Or summarize like "Fill out these 8 fields, then click Next" with a circle around the block of fields and another around the Next button. Sometimes it's easier to take in information in larger related chunks. – Bobson Sep 16 '13 at 14:33
Yeah, I often do that. On the screen shot, I'd show all the information filled in. – Michael Shaw Sep 16 '13 at 14:37
@Bobson Though it might depend slightly on the audience... If the visuals change due to any action/click on the screen, then a screenshot might be necessary. I once dev'd and supported software used (primarily) by a team of elderly women. ss of the screen pre-action, ss with arrows/numbers referring to the text performing the action and ss of the screen post-action indicating what was done. It's like Joel's old argument of handlebars in bathrooms. It might not be _necessary_ for everyone, but everyone uses and appreciates it. – Steven Evers Sep 16 '13 at 17:25
@SteveEvers - True. Knowing who the end users of the documentation are is very useful - sometimes you really *do* need to have that level of detail. On the other hand, it would drive me crazy (unless it was the manual for a nuclear power plant's controls or something like that). – Bobson Sep 16 '13 at 17:37
1

Please do include screenshots in your documentation, even if many users will see slightly different chrome on their windows. As a MacOS X developer I was one of the people who convinced an Apple Engineer to put screenshots (Command-Shift-3) back into MacOS X for documentation. – Michael Shopsin Sep 17 '13 at 15:13

score 1 · Answer 2 · answered Sep 16 '13 at 18:11

The old adage "a picture tells a thousand words" is rarely as important as it is here. Please, please, please, for your sake and for your users: USE LOTS OF SCREENSHOTS.

Having been in a similar situation, where most of my users were elderly women, I cannot convey how useful screenshots are. The question becomes, how to present them. I found that a task-based approach works best.

e.g.

Table Of Contents

Customer Information
- I want to update a customer's address
Billing
- I want to create an invoice for a customer
- I want to create a bill for a customer
Shipping
- You get the idea

Note that each heading in the TOC is obviously a link (which any format, be it word/html/chm/whatever supports). Then for each individual action (eg. 1.1) start with the first screen the app shows when it opens up.

Start at the Home screen
- [screenshot]
Click "Customers"
- [screenshot with big red circle around "Customers" button]
You arrive at the Customers window
- [screenshot of the customers window]
- (note, use a test build with only fake customers)
Click "Search"
- [screenshot with big red circle around "Search" button]
Enter the customer's last name and double-click their name
- [screenshot of the search window with the customer's lastname in the search box]
You arrive at the customer details screen
- [screenshot of the customer details]
Click "Edit"

etc.

Yes, this first few steps are redundant, and the whole thing is lot of laborious screen-shooting. Users will get used to just flipping past the first page or two but anyone and everyone, on their first day on the job, or after a long vacation, or mat leave, or sick leave, or whatever... can be told to "Go do [this]" then click "I want to do [this]" in the docs and have detailed instructions showing exactly what to do.

You can have the first step be "Open the customer's file" which is linked to the "I want to see a customer's information" section. Be wary, I switched to that, and had a large portion of my users that found this extremely complicated. The ones who didn't find it complicated, didn't care enough to appreciate the 'shortcut'. The tip is: Know your audience and don't assume anything about them.

There's an old article from Joel Spolsky (that, for the life of me, I cant find) where he talks about usability and the wheelchair assistance bars in bathrooms. The crux of the argument was that some usability features aren't necessary for everyone... but when available, everyone uses and appreciates them. I firmly believe that incredibly obvious documentation for internal apps fits in this category. Especially considering that they can't be searched for help online.

score 0 · Answer 3 · answered Sep 16 '13 at 16:09

It depends on your precise application and how it's structured, but in general you should have more text than screen shots I've found. Unless your product will be a user's first introduction to a computer, you shouldn't worry about click-by-click instructions. Assuming your user interface is sane, you should be able to describe how to do most operations with text and maybe a few screenshots.

If, your user interface isn't quite sane and/or is misleading.. well, you could fix that, or you could give screenshots or even animated GIFs showing how to actually get your product to work. You should provide this in addition to a lot of plain text though.

score 0 · Answer 4 · answered Sep 17 '13 at 09:05

Are the users likely to be programmers/tech people themselves, precise description with only a few screenshots should be sufficient.

But if the users are non-tech people screenshots with precise descriptions will help a lot. Keep in mind most people are not even aware of the technological terms you are probably using in your description. Try to ask any person using a computer what a radio button is.

Bottom line: Depends on your users

Should user documentation include screenshots?

4 Answers4