h1

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.)

Example of a screen layout, with numbered callouts and a key below the screen shot

Example of a screen layout, with numbered callouts and a key below the screen shot

I do use images of unfamiliar toolbar icons in my software documentation:

Example of toolbar icons used in text

Example of toolbar icons used in text

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.

Example of screen shots to enhance comprehension

Example of screen shots to enhance comprehension

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.

5 comments

  1. NO!!! Not if you plan on localizing. Whether it’s four languages or fourteen, if you put screen shots in your user assistance, you’ve increased the cost of goods (the cost to translate). The only screen shot I put in the help is of the main application, with numbered callouts (followed by a table with those callouts).

    I use a few more, but very judiciously, in the user guides and quick start guides. Again, though, it’s very expensive to have to set up a system in the L10N language and then take the screen shot. Or train someone to do that.

    Of course, your mileage may vary. If you are writing content for a very inexperienced set of users, pictures may be worth a thousand words. Some printer companies use only graphics for their user assistance with very few words. For enterprise level software apps, though, this doesn’t work.


  2. Hi Sue

    I agree re: software and documentation that will be translated into other languages. However, to date I haven’t been involved in such projects.

    That said, it’s still really painful to have to update potentially hundreds of screen shots just because a developer changed the text on a single tab. Which is another reason to use cropped images if you’re going to use screen shots at all.

    –Rhonda


  3. Rhonda, one could also argue for using all full screen captures, thus every topic that uses the image would link to the same image file. Change to the text on a tab? Redo one screen capture and you’re done.

    You can also put a “View this dialog box” button in the help topic so it doesn’t take up on-screen real estate but pops up in a separate window if the user wants to see it.

    Mike


  4. Another benefit to using callouts to a legend rather than including the text in the graphic – it’s better for translation. If you translate into a longer language than English (e.g. Russian or German, or most any other language except for some Asian languages), then the text will take up more space in translation. A legend can deal with this more easily than what might be tightly spaced text in a graphic.


  5. Would you rather use a Help file with images or not? Consider your audience, then try to make the tools/services work for you. Rhonda’s numbered elements w/ a legend is good; Mike’s suggestion is good; the use of variables for UI items will make changes easier. Be creative. Technology is making translation easier all the time–get your translator to work with you.



Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

Join 326 other followers

%d bloggers like this: