While working on a software manual for a project that will soon be launched, I found myself thinking that there weren’t any good places to insert images—the instructions were pretty clear, and if a user is looking at the application while using the instructions, he should be able to find his way.

I realized that I had spent so much time on this project that I was approaching the dreaded mindset of taking knowledge for granted. Like most others, this manual is a reference guide, so users will not be reading from beginning to end, even of their respective chapters. (The material is broken up by role and then by task.) If the current task I’m writing is the only one a certain user ever looks up and reads, then in and of itself, it has to be clear.

It was a good reminder of how, though a wide range of content may be included within the same manual, help system, knowledgebase, etc., that each part needs to be self-contained. These chunks can (and should) refer to each other, but each chunk needs to act like it’s the only one the user will ever read. I should be careful to assume no prior knowledge unless I’m addressing a specific, advanced audience. Writing for the lowest common denominator is the general rule.

The other extreme is manifest in a help system that I inherited. Topics were written in a how-to format, and in most of the instructions, there is an image for each step. In addition to being a monster for maintenance and localization, this setup seems to me to go a little overboard. In many cases, when the user clicks an indicated link, she is going to see the next screen and doesn’t need the help to display an image of that same screen. But when you’re documenting a graphic user interface, whether a Web application or site or the display on electronics, shouldn’t you have images everywhere?

Where’s the middle ground between neglect and overkill?

Granted, doing too much is probably better than doing too little. But if you’re trying to decide how much visual assistance to provide along with your textual content, ask yourself these questions:

• Could the user have a hard time finding the specific link or other control that I am talking about? For example, a button may appear on an application screen only in certain circumstances, so it would be appropriate to indicate where that button is (and also explain the circumstances in which it appears). Changing states of screens or displays are important to illustrate.
• Am I trying to explain a concept or process that could be illustrated with a diagram? This is usually a no-brainer, but when you’re principally a writer, your inclination may be to try to explain with words first. At times, it can be only when I’ve written a few hundred words to explain something that I realize a diagram would convey the same information more quickly and clearly. I didn’t set out to use that many words—perhaps the concept was simple in my mind when I started—but as I write, I see that things aren’t as simple as I originally thought.
• Would an image showing an example of using the screen or product be quicker than giving a purely textual example? Rather than textually giving an example of how to fill out an electronic form, simply provide an image of the completed form.
• Can I show all steps in a single diagram, or should I break the process up into multiple images? When I’m assembling something that has instructions with a single exploded diagram, it can be hard to see exactly what to do. If it’s a complicated process, give me multiple images.

Common sense, right? But there are so many things going on in our heads, we can be commonly good at forgetting the obvious.

If you don’t see a specific purpose for an image, don’t include it. Just keep in mind that what is unnecessary for some users is a big help to others. But if you don’t think an image would provide any real value in a certain spot, don’t put one in just so your documentation has the appearance of completeness.

The document I mentioned at the beginning has many images in some places, including some that are probably not necessary. This may have contributed to my recent encounter with apathy. As always, the approach to take is with the user in mind and to consider whether the image will help or hinder.