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 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.
I've written about this subject before. SW documentation is often reused for different versions of the same software. T …
6y ago
It all comes down to the familiarity of the audience with the interface. The words of a procedure describe parts of the …
8y ago
Does the screenshot add to what you're saying, or is just there to be pretty? I think that marketing materials should be …
10y ago
This post was sourced from https://writers.stackexchange.com/q/10643. It is licensed under CC BY-SA 3.0.
3 answers
You are accessing this answer with a direct link, so it's being shown above all other answers regardless of its score. You can return to the normal view.
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.
This post was sourced from https://writers.stackexchange.com/a/36823. It is licensed under CC BY-SA 3.0.
0 comment threads
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.
This post was sourced from https://writers.stackexchange.com/a/10996. It is licensed under CC BY-SA 3.0.
0 comment threads
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.
0 comment threads
0 comment threads