Using Graphics in Technical Documentation

Table of Contents

1. Overview
2. Need for Graphics in Technical Documentation
3. Types of Graphics Used in Technical Documentation
4. Tools for Creating Graphics
5. When Not to Use Graphics in Technical Documentation
6. Summary

Overview

The job title ‘Technical Writer’ includes the word ‘writer’. However, in most scenarios, technical documentation does not consist solely of written text. Graphics and, sometimes, even videos are an integral part of present-day technical documentation. In this article, we will learn about the different types of graphics, why and how they are used, and the tools that you, as a technical writer, can utilize to create them.

Need for Graphics in Technical Documentation

I think I can assume with almost complete certainty that, along with creating technical documentation, you have also consumed it. And with a slightly lower level of certainty, I am assuming that most of the time, you didn’t go through any piece of technical documentation to learn something. You referred to those documents because you were stuck at some point and needed some answers in order to proceed forward and complete the task that you had started.

If your experience is close to mine or those of the people I know, the endless pages of text give you an uneasy feeling. You dread having to read multiple long paragraphs of text to find a simple answer. On the contrary, if you happen to find a graphic that solves your problem clearly, it brings a smile to your face.

It is true that many times graphics are essential. You just cannot explain certain things without the use of graphics. At other times, they enhance the user’s understanding of the accompanying text. However, one place where more technical writers should employ them more is when a whole page, or a few pages, of text can be replaced by a single graphic.

Types of Graphics Used in Technical Documentation

If we don’t count UI icons, technical writers make use of four main types of graphics.

• Screenshots: These are the most common types of graphics in technical documentation, and almost every technical writer would have worked with them. They are used to familiarize users with the UI by explaining form fields, buttons, or menus. They also serve to highlight errors, warnings, or system messages, and to guide users through step-by-step workflows. In many cases, they also provide visual confirmation to the user that they are in the right place. Screenshots alone are often not enough. Use callouts, highlights, and numbered steps to make your point absolutely clear.

• Diagrams: Diagrams are needed to explain structure, relationships, or architecture. They are most useful when you want to provide system architecture overviews, data flow explanations, component interactions, or API ecosystems and integrations. Novice users might not have much use for diagrams. However, they are really valuable for developers, system architects, and advanced users. This is because they help in seeing the system at a glance without having to read long, complex textual explanations.

• Flowcharts: Whenever you want to showcase a logic, process, or decision path, a flowchart is what you need. They make the conditional logic easy to follow while reducing the need for back-and-forth reading. In some cases, they also help the users to self-diagnose the issue.

• Infographics: Infographics are the best choice when you want to summarize, make comparisons, or provide high-level explanations. While they cannot provide detailed explanations, infographics are easy to scan and remember, which makes them good for both technical and non-technical audiences.

Tools for Creating Graphics

There are numerous graphic design products floating in the market, and new ones keep showing up frequently. Some tools are free, though most are paid. If you are a freelancer, you can check out the following list to find out what works for you. If you work for an organization, you might like something enough to pitch it to your manager as an upgrade.

• Screenshot and Image Capture Tools: Snagit, Greenshot (Free)
• Diagramming and Flowchart Tools: draw.io (Free), yEd (Free), Microsoft Visio, Lucidchart, SmartDraw, Mermaid, Creately
• Infographic and Visual Design Tools: Canva, Adobe Express, Piktochart, Visme

When Not to Use Graphics in Technical Documentation

We have talked a lot about why graphics are important. Now, let’s take a look at the situations when we should avoid using graphics.

• When the UI or System Changes Frequently: In such cases, the graphics become outdated very quickly.
• When the Task is Simple or Self-explanatory: When a few words can explain the idea clearly, a graphic adds noise.
• When Graphics Duplicate the Text Without Adding Clarity: If the image merely repeats what the text already explains clearly, it’s unnecessary.

Summary

It is highly likely that you already work with graphics in some form or capacity. If you don’t, then you probably are not completely fulfilling the technical writer role. Your job is not just to provide information but also to make its consumption as easy as possible for the end user. Your organization may have a separate department for creating graphics. Even in that case, knowing which kind of graphic fits best in which situation and having the ability to visualize it will enable you to get the most out of that company resource.