Take the 2-minute tour ×
Writers Stack Exchange is a question and answer site for authors, editors, reviewers, professional writers, and aspiring writers. It's 100% free, no registration required.

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 screen shots when the graphical user interface (GUI) changes.

An easy way to reduce the pain of updating screen shots 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 screen shots 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 screen shots.

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

Given limited technical writing (training) resources, every screen shot 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 screen shot 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.

share|improve this question
add comment

3 Answers 3

up vote 2 down vote accepted

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, 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.
  • 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.
share|improve this answer
add comment

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.

share|improve this answer
    
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. –  Fuhrmanator Apr 2 at 16:24
    
Some users prefer visual information, others prefer (and are better at processing) text. @what's experience is not universal. –  Hobbes Apr 16 at 9:25
    
What you call "@what's experience" are findings from psychological studies. –  what Apr 16 at 11:43
    
@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). –  what Apr 16 at 11:47
    
@what your answer would be more convincing to me if it cited the psychological studies you speak of. –  Fuhrmanator Apr 16 at 19:13
add comment

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.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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