Visuals in Documentation

Visuals like screenshots and videos are powerful tools that can enhance user documentation, but they do have a cost. I’m going to explore why screenshots and videos should be used and when they should and shouldn’t be used. At work, I’m about to start creating user guides, so I want to form a strategy for using visuals before I begin.

Why use a visual?

I think it’s possible to explain anything using words, but that doesn’t mean that everything is easily understood by reading words.

For example, if you want to explain what a car is, you can say that it’s red, has four wheels, and four doors. You can describe it even more precisely: the paint colour is #FF0000 (hex value), the wheels are 50cm in diameter, and the doors are rectangular.

Wouldn’t it be much easier to you show a picture of the car instead?

In the context of technical writing, an image can sometimes supplant “a thousand words” (to borrow from the tired expression).

If you want to guide a user through a UI step-by-step, you could use instructions, or you could show a screenshot of the UI with arrows pointing to elements the user should select (or even better, you could use instructions and screenshots).

Diagrams are great for documenting statistics. Diagrams like pie-charts and graphs make it easier to visualise comparisons and digest numbers.

I’ve found myself - and I think others do this too - skimming help pages and just looking for pictures or code documentation. Our brains are much faster at recognizing pictures than sentences.

An image at the start of an article or document can orient the reader. I know if I’m at the right starting point to follow instructions if the image in the documentation matches what I’m seeing.

Visuals are useful - why don’t I use them everywhere?

The cost

A hammer is a useful tool - its cheap and requires little if any maintenance. A chainsaw can fell trees, but its expensive, needs fuel or power to run, and needs maintenance to stay effective. Likewise, words are cheap to produce and easy to change, and effective visuals are expensive to create and hard to maintain.

For example, with screenshots, if part of a UI updates (maybe a new button is added), then any screenshots that include that UI must also be updated. Or if your documentation is translated into other languages, each screenshot must be translated too. Each screenshot of the UI would have to be recaptured for each language. Videos incur the same burdens, but at a greater magnitude.

When are visuals useful?

Like every good thing, use visuals moderately. It would be easy to say “never use visuals”, because this would save on documentation costs, but they are too useful to dismiss. How should I determine what “moderately” means when using visuals in my technical writing?

I think the amount of visuals should be proportional to the tech writing capacity. In my situation, I’m a tech writer 50% of the time (in reality its more like 70%), so I think Videos are out of the question; I don’t have time to create or maintain them. Screenshots are possible, but I should always have a reason to use them (I want to try to using “conceptual” or “silhouettes” instead of screenshots when possible (see “Silhouettes” for more details)). I can also use diagrams if I have good reason to.

How to minimise the costs

Ways to minimise the costs of visuals:

• Don’t use visuals: Give careful thought to each screenshot’s worth. If it doesn’t add any value, delete it.
• Create visuals last: When drafting a new document, use placeholders rather than creating the visuals immediately. If you are working in an Agile way, the product can change at any moment during its development. The later you create the visuals, the less you’ll have to rework them during the product’s development.
• Avoid text in visuals: If a visual contains text, you will need to translate it. Try to use as little text as possible in visuals - none if possible (See “Silhouettes”). Numbers aren’t translated, so they are an exception to the rule.
• Avoid including unnecessary parts of the subject in the visuals: In the context of screenshots, this would mean capturing the part of the UI that is relevant to the context. If you capture more than that you could confuse your user and you may later have to retake the screenshot if some part of the UI changes (even if it isn’t relevant).

Silhouettes

I’ve found a technique that I could use to show the shape of a UI without using text.

Instead of a screenshot, you create a “silhouette” the UI. This silhouette doesn’t contain any text, just boxes where the text should be.

If you’ve seen rounded grey rectangles whilst waiting for a webpage to load, you may already have any idea of what I’m talking about.

Silhouetting has some of the benefits of screenshots, without incurring the same maintenance costs. There are still costs, but they are mostly initial like with diagrams.

As I have not yet used this technique in any documentation, I don’t know how effective it is. I’m hopeful though, it seems like a nifty hack for lean user documentation.

If I were to guess what drawbacks this method would have, I’d say that I don’t think a silhouette will be effective for a complex subject like a form with many fields. It may also be difficult to make a silhouette look professional. If done poorly, it would look unfinished or prototype-y. But, I’ve got a style in mind which should work, so I’ll give that a go.

Conclusion

I secretly hoped that I’d be able to dismiss visuals entirely after thinking this through, but I now I think that would be a mistake. The reality is that visuals are powerful tools that shouldn’t be used more than they need to be, but when they are used, they make confusing subjects easy to understand.