Post History

Source: https://writers.stackexchange.com/a/36823
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

I've [written about this subject before](http://www.imaginaryplanet.net/weblogs/idiotprogrammer/2007/10/why-users-dont-read-documentation-technical-writing-secrets/).

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.

Original score: 4