Technical writers are experts at determining topic organization, tone, flow, and verbiage when it comes to documentation.
However, one component that is often overlooked or shied away from is balancing visuals and text in technical documentation. This article is intended to provide a deeper understanding into how technical writers – not graphic designers – can use visuals to enhance their work and help them to develop highly effective documentation by addressing the following questions:
- How should you determine when visuals – graphics, illustrations, drawings, plots, or screenshots – are necessary?
- What considerations should you think about when editing visuals and adding labels?
- How do you mitigate the risk of misinterpretation when connecting text to visuals?
When are Visuals Necessary?
Visuals can help readers quickly understand complex concepts and processes, and form part of your documentation strategy. They allow readers to visualize relationships and events, whereas the same information in text can be more difficult to grasp. They also give readers’ eyes a break when reading text, and can help invigorate interest in lengthy content that can, at first look, feel quite daunting.
For example, when writing procedural documentation you often spend time thinking of the most efficient and clear way to describe an action. Once that is written, the user must then read the text and fully visualize what they need to do to successfully follow that step. Some steps may be very simple and an associated graphic would not have much impact or be of any help in gaining clarity. However, more complex steps may benefit from a graphic to help enhance the reader’s understanding.
Tip
Whenever you find yourself struggling to present information concisely, try inserting a visual and write out a clear caption instead of a paragraph.
Complex steps that involve multiple actions or visual identification of any parts or components can be clarified by a labeled graphic. For example, an image of how to install “part A” to secure “part B” to “part C” will show the reader how the parts need to be assembled in a secure fashion with minimal room for misinterpretation. Alternatively, if the reader needs to identify “vial 3” from “vial 4,” a picture showing the differences between the vials will allow the reader to quickly identify which vial needs to be used.
These more complex actions can be very difficult to visualize without an example, and so the image guides the reader what to look for or do specifically. In turn, this allows the reader to quickly understand and complete the procedure in shorter time frames. This naturally leads to happier readers.
Screenshots can also provide readers with easy direction when text may take too long to describe visual content. For example, a screenshot showing where on the website a user can change account settings can often be accompanied just by simple, concise text: “click on the dropdown menu circled in red in the screenshot below and select account settings.” This is far more efficient than describing how to locate the dropdown menu on the web page only in text.
Plots and other graphical representations of data are also particularly important and useful in the proper context. Oftentimes, report documentation that discusses data or results could include the associated plots to allow the reader to quickly and easily recognize trends and interesting results. No board member wants to spend hours reading data points when the information could have been summarized in graphical form.
When to Use Visuals – A Summary
- Images visualizing how to complete complex steps that involve multiple actions or that may otherwise have room for misinterpretation
- Pictures for easy and fast visual identification of any parts or components
- Screenshots can provide readers with easy direction when text may take too long to describe visual content
- Report documentation that discusses data or results could include associated plots (as applicable) to allow the reader to quickly and easily recognize trends and interesting results
Considerations When Editing Visuals and Text in Technical Documentation
Now that we have a clear idea of when to use visuals, it is time to think about what considerations need to be made when editing them. Often a plot, picture, or other image is given to technical writers with little context and no labelling. It is our job as documenters to understand the meaning of the visual and how to use it for maximum effectiveness (including clarity and concision) in the documentation.
Tip
When working with complex products, ask the designer/product owner for drawings or diagrams to include in your documentation. This will ensure accuracy and - as a bonus - get the engineers' attention when they read through the document.
Labels
Labels should detail exactly what components the reader needs to pay attention to within the visual. This is especially important in data-driven reports and procedures – particularly for procedures with safety concerns. No reader wants to take the time to interpret an image that was intended to help their understanding. Instead, show them exactly what you discuss and reference in your text with clear labels, arrows, circles, or any other applicable labeling.
Of course, it can be easy to over-label. Only label exactly what the reader must know to understand the text, and nothing more. Everything else is excess and should be cut for clarity and concision.
The image above shows one specific button highlighted by the green circle and clearly marked with an arrow. Meanwhile, the image below labels four different buttons that have nothing to do with one another – this is an example of an image being used for too many purposes. The image above will be far easier for the reader to instantly identify and understand what they are supposed to do with that button, as specified in the accompanying text.
Tip
For easier translation efforts, only use numerical labels rather than text in the visuals themselves, and include a key that details what each number represents. This way the translation team only needs to worry about the text and not about the graphics.
Accessibility
Another important consideration when incorporating visuals into your documentation is accessibility. This especially applies to those of your audience who have color-blindness or other visual impairments. Seeing the difference between a green positive trend and red negative trend can be very difficult for those who are red-green colorblind. Likewise, using tiny arrows or text in your labels can be challenging for those with other visual impairments.
Luckily, there are many online resources (such as Learn UI and Colorsafe)that can help you choose colors that are more accessible. Additionally, it is best practice to include alt text to visuals for online documentation. Alt text describes the image to readers who have visual impairments. If possible, do user testing on your content. Inviting people with visual impairments to use your content can provide valuable insights.
Top accessibility tips:
- Avoid using only red and green in your graphics. This is one of the most common types of colorblindness.
- Avoid small text anywhere in your documentation. You want to help your readers, not harm their vision or frustrate them!
- Always include alt text to every visual in your content. This will allow those with visual impairments to understand your visual, despite their impairment.
Feedback
Just as it is important to get comprehensive feedback on your text, it is also important to get feedback on the graphics used in your documentation. After all, the text and the graphics should be working together for easy comprehension. If your SMEs and other reviewers do not mention the graphics, ask about them specifically. “What did you think of this plot?” or “did you understand how rotating the shaft during cam installation works? Did Figure 2 help?” are perfectly valid questions to ensure your graphics fully support your audience. Asking someone with a fresh perspective to read through the document and report back their understanding can help show pitfalls in clarity as well.
Tip
Working with your graphic designer colleagues can often help you see where your visual is lacking - lean on their expertise to improve your visuals.
Mitigating the Risk of Misinterpretation
Technical writers are pros at mitigating risk of misinterpretation. It is our job to ensure the content provided has one clear meaning with minimal ambiguity, and visuals can certainly aid this intention. But what specifically should tech writers be on the lookout for?
Refer to the Visual Within the Text
When an image, plot, or other visual is used in the document, it is generally best practice to use the text to ground it. Visuals – be they image, plot, or other graphic – floating around your document without any explanation or textual reference can be confusing. This is especially true for procedural documentation: you do not want your reader to be unsure if they followed all of the steps just because you included a graphic that has no explanation. Likewise, you do not want someone to wonder if they did not get a full grasp of the experimental results because a plot went unmentioned. This can lead to confusion and frustration.
Captions
Another way to aid visual understanding is to use captions. Captions should be descriptive and short. Anything longer than a sentence or two should be included in the paragraphical text of the document. An example of an effective caption may be something like: “The lever to open the vehicle hood is circled in blue, above.” The instructions on how to move the lever would be in the text that comes before or after the image. Be forewarned – not everyone reads captions, and they can be distracting if overused (just as footnotes are often skipped in favor of reading ahead)!
Final Thoughts
Just like a thesaurus and dictionary, balancing visuals and text in technical documentation is an important part of any effective technical writer’s job. A picture is worth a thousand words – and graphics often enhance a document’s readability, clarity, and effectiveness.
By taking the time to:
- identify when a visual should be used,
- consider how the visual is labeled and colored,
- ask others how they interpret the visual, and
- ensure it is related to the text and context of the document,
you can rest assured that your visuals enhance your documentation.
