: 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
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 Reactions React
4 Comments
Sorted by latest first Latest Oldest Best
@Murray165
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 Reactions React
@Shelton455
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 Reactions React
@Harper186
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 Reactions React
@Odierno164
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 Reactions React
Terms of Use Powered by ePowerPress Stock Market News!
© selfpublishingguru.com2024 All Rights reserved.