: When is a screenshot really useful in training documentation? Software products evolve more rapidly each day. Technical documentation for those products must also follow their evolution. One of

Vote Up Vote Down

There's a saying that a picture is worth a thousand words. At best, it's a general approximation. At worst, it's flat out wrong.

I suppose a lot depends on how good the words are. Writing well is hard, whereas taking a screenshot is something a monkey could do.

(0)

Vote Up Vote Down

I've written about this subject before.

SW documentation is often reused for different versions of the same software. Therefore, it is important to minimize the number of screen captures you use. Why?

Using out-of-date screen captures causes a lot of confusion.
Replacing/updating screen captures is a lot of work.
Unless it is difficult to do, screen captures should always be
accompanied by a caption that explains what is useful and/or
important about the screenshot. Instead of using the generic “Save As Dialog,” you should say “Ms
Word lets you save in various formats” and then show the dropdown box
of all the formats that MS Word saves in.
Screen captures use a lot of real estate and generally shouldn’t be
used for long topics. If there’s more than three screenshots on a
single page, something is probably wrong.
The best time to use screen captures in documentation is to reveal a
non-obvious feature or to show what SW looks like when it is
processing live data.
Best contexts for using screenshots? They are especially good for
novice users and illustrating problem states in software.
Screencasts are also becoming efficient methods for conveying the
general sense of a user-interface. They are especially effective for
quick tours and to illustrate the overall flow of work in a short
period of time, but they still are no substitute for conventional
documentation.

(0)

Vote Up Vote Down

Does the screenshot add to what you're saying, or is just there to be pretty? I think that marketing materials should be "pretty", but technical work should focus on teaching and understanding.

Remember, too, that you should make all of your documentation accessible to users who have less than perfect vision.

(0)

Vote Up Vote Down

I am just sharing the guidelines I work by. If required, we can discuss the reasoning behind these guidelines and may be even specific examples. (Say, for example, beyond maintainability and localization costs, yet another reason text is better for less-than-complex steps is search engine optimization.)

When to use screenshots?

You need the context of the UI to make a targeted point about how to accomplish a specific task.
It highlights an unusual interface choice or adds clarity and permits brevity of text, that is, it saves several descriptive sentences about options necessary to complete a procedure.
To refer to an unnamed UI element in a task, and the reader cannot easily identify or find it without a callout.
To highlight differences between two versions of the product, for example, old vs. new, or Mac vs. Windows.

When not to use screenshots?

To track the user’s progress through various screens encountered in a workflow.
Solely for the purpose of helping the reader locate easily identifiable UI elements. You can use an inline icon if you think there is a need for a graphic element to help the reader. For example, if the UI has a non-standard icon then place a 16x16 icon inline in the instructions asking user to click the icon. Also, situate the user on the UI using text like top-left corner, right side panel, left side bar, etc.
At the end of a step in a task, solely for showing a result of the step, unless the screenshot serves to provide reassurance to the user during a complex procedure.

(0)