Should I put screen shots in online Help?February 11, 2010
This is a perennial question asked by technical writers, especially newbies. When it comes to the answer, seasoned tech writers typically divide into two main camps — yes or no — with some variations within those answers.
My stance is “It depends” (which means I have a bit of a bet each way!) Let me explain further…
Whether I include screen shots depends on:
- what the (internal/external) client/user wants
- what the output is (online, print, or both)
- if online, what screen ‘real estate’ is available
- how complex the software application is
- how difficult/easy it is to get the screen shots required (e.g. before/after code freeze)
- the budget for the project — adding screen shots adds quite a bit of overhead in time (think at least 5 minutes per screen shot), and therefore can add substantially to the cost of producing the documentation, and maintaining it (many screen shots may have to be recaptured for a new release*).
I’ve used screen shots extensively in some projects, but rarely in others. Even within the same project, I’ve used them for the printed output but not the online output.
That said, I almost always have at least one screen shot of the basic screen layout that has a key/legend to describe the various parts of the screen, particularly where the terminology for the various parts is different from applications that are likely to be familiar to the user. (Tip: Do NOT add callout text directly on the screen shot. Instead, use numbers or letters to mark the respective elements, then add a key/legend table in the text below. Why? Because if you have to update the screen shot later, adding all those callouts again is a pain; and if the documentation has to be translated, you’ll save time by not having to create multiple screen shots with callouts in different languages.)
I do use images of unfamiliar toolbar icons in my software documentation:
And I may use other images to enhance understanding. For example, an application I documented contained functions to convert 3D graphical objects into something else (e.g. converting wireframes to 3D solids, trimming triangulations, performing Boolean operations on solid objects, adding/moving/deleting vertices, finding boundaries between complex objects etc.). For each function, I took a “Before” and “After” screen shot of a simple example so the user could SEE what the function did. As I said, this was for a very graphically intensive application, and words only went so far. The screen shots enhanced the learning experience as it showed the user an example of what the function did, without them having to set it up and test it themselves.
However, in general I don’t use screen shots in online Help. For the few that I might add, I try to use a graphical clue such as a torn edge to show that the image is a screen shot and not the real application. Why? Because even after all these years of working with software, I still get caught occasionally clicking a Close button on a screen shot in the Help! ;-)
I will use screen shots in print if ‘showing’ helps the ‘telling’. The nice thing about Help authoring tools that have ‘conditionality’ and/or variants built in (such as Author-it) is that you can add screen shots throughout the documentation, and set conditions so they are only published in the print output, not in the online.
* About maintenance: On one project, one of the developers changed the text on a dialog box tab. A simple change for the developer. Unfortunately it wasn’t so simple for me. In addition to changing at least 10 topics where the tab name was written, I had to recapture more than 50 screen shots as that tab name displayed on every screen shot of the dialog box throughout the documentation.