14

Software products evolve more rapidly each day. Technical documentation for those products must also follow their evolution. One of the biggest challenges is to maintain screenshots when the graphical user interface (GUI) changes.

An easy way to reduce the pain of updating screenshots is not to use them except when they're really useful. It's been debated before, namely here.

I see lots of technical documents that use text to get the job done, e.g.,

Go to Start Menu > Search programs and files and enter "snipping tool"

rather than putting up three screenshots showing all those steps. It assumes, however, that users are going to know where the "Start" menu is, etc. With some software, it's obvious. Also, the user's skill level plays a role in whether or not it's useful to provide screenshots.

The GNOME project has recommendations for online help and printed materials, including screenshots, but it seems that it's limited to one type of software (GNOME Desktop distributions).

Given limited technical writing (training) resources, every screenshot has a risk that it will need updating.

Does anyone know of a set of heuristics or evidence-based reasoning on how to decide whether a screenshot is worth the maintenance risk to put in training documentation? I'm looking for official policy, similar to that of the GNOME reference above, but for other types of software.

Edit: Please don't assume that the technical writers are working for the company producing the software. Many writers have to produce training materials for open-source software used in organizations. Such software is often powerful, but not intuitive; trainers fill the gaps to explain how to use the software.

0

6 Answers 6

12

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.
6

It all comes down to the familiarity of the audience with the interface. The words of a procedure describe parts of the interface. Will the audience immediately recognize which parts of the interface those words refer to? If yes, then screenshots are unnecessary and will simply slow the reader down. If no, then you need a way to show the reader which part of the interface the words refer to, and a screenshot is one way to do that.

As computers have become more ubiquitous, interfaces have become more standardized, and people do more and more activities on the computer, people have become more familiar with interfaces and thus more likely to recognize what the words in the procedure refer to. Thus we have more shortcuts like File > Print, because people now know what that means.

There is a universal phenomena here: as products become ubiquitous and users become experienced with them, the need for documentation diminishes, and may eventually disappear altogether. Thousands of products ship with no documentation other than that demanded by lawyers. It is all about where your product fits on the familiarity scale with its intended audience. This affects far more than just the decision about screenshots.

But there are still specific cases in which the audience may not know what the words in the procedure mean. If the audience is inexperienced or the interface is non-standard, the reader may not recognize what the words mean and you should use screen shots.

In some cases, there may be small parts of the interface that are non-standard, meaning you should use screenshots for those parts and not for others.

In short, therefore, use them where you anticipate that a significant portion of you audience may need them, and otherwise not.

1
  • 1
    “There is a universal phenomena here: as products become ubiquitous and users become experienced with them, the need for documentation diminishes” — When users become experienced with an interface, the developers feel the urge to change it. That applies both to proprietary software (MS Windows, MS Office) and to Free software (Gnome, Mozilla). BTW, shouldn't it be “phenomenon”?
    – celtschk
    Jun 14, 2018 at 7:44
5

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.
3

I'll give you an answer not as a writer (I don't write technical documentation), but as a user.

You want to sell your software, because selling your software will give you a job as a writer of software documentation. You sell your software by great user experience. Great user experience relies to a large part on easy to use software documentation. So making the software documentation pleasurable for the end user will help you keep making your livelihood. Just so you get the right perspective on your job.

During the 20 years that I have been using computers and software, there have been many programs that received raving reviews and that (supposedly) did exactly what I wanted them to do and that I bought and paid for, but that I stopped using pretty quickly, because getting around the documentation was continually annoying.

Much can go wrong with documentation, but since your question is about sceenshots, I will focus on those.

Why do all people love movies and tv, but not books? Why do we write to dating profiles with images, not without? Why do we use PowerPoint and not just talk to our audience? Because human beings prefer visual over text information. We can process it more quickly, and in larger volumes.

When I search for a software problem on the web, I open the first few Google hits in my browser and then go through the open tabs. If the solution is text only, I close it immediately without reading it. Reading a handful of paragraphs of text to understand if the page even addresses my problem takes much too much time. If I can see an image, I know with one quick glance if the help page is about what I want to know.

Of course with your documentation I won't be searching the web and clicking it away for the next document, but in my overall experience with solutions to software problems I will compare it to everything I have seen. And in this comparison, (meaningful, no-noise) images are a definite plus. So: Screenshots help the user to navigate the documentation and identify the relevant help section.

Why do people love cook books with step by step images? Because their kitchen is not text. Their kitchen is a visual experience, and if the cook book shows how the kitchen (or a part of it: the pot) should look like, that makes understanding the procedure and checking if what the hobby cook does is according to plan so much more easy, quick and fun. The same goes for software: When I have a problem, I have the software open and do what the documentation tells me to do. I just love if I can scroll up the manual annotated screenshot by annotated screenshot while I do what I'm shown in the side-by-side software window. Why do kids follow the bad example of their smoking (or non-smoking parents) instead of what they are told? Because they do what they see! So: Screenshots help users understand and learn how to use their software.

Words are abstract, and abstraction does not come natural to most (if not all) people.

Images are the natural "language" of your world-experience. If you present information in visual form, it arrives in the heads of your users much more easily and pleasurably.

The more visual a software experience is, the less text it needs to be mastered, the better it sells.

7
  • 1
    You want to sell your software, because selling your software will give you a job as a writer of software documentation. Sorry, I'm lost. I'm a technical writer for software that is not mine, but which I have to explain to the users in my organization (see my edit in the question). Also, the answer needs a TL;DR summary that addresses the question. Apr 2, 2014 at 16:24
  • 2
    Some users prefer visual information, others prefer (and are better at processing) text. @what's experience is not universal.
    – Hobbes
    Apr 16, 2014 at 9:25
  • 1
    What you call "@what's experience" are findings from psychological studies.
    – user5645
    Apr 16, 2014 at 11:43
  • 1
    @Fuhrmanator You are dependent on your documentation helping users be productive. If your docs confuse the users, that software will be abandoned, it won't sell, and you're out of a job. If on the other hand your organization does not create that software, only uses it, you will be out of a job if the people using your software waste time making sense of your docs: your boss will hire a better writer. In any case your job and income will depend on the quality of your writing. So ease of understaning (what I argue for) is just as important as ease of documentation (what you argue for).
    – user5645
    Apr 16, 2014 at 11:47
  • 1
    @what your answer would be more convincing to me if it cited the psychological studies you speak of. Apr 16, 2014 at 19:13
2

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.

-1

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.