Optimizing Visuals in Technical Documentation

Introduction

The growth of platforms such as TikTok and Instagram suggests that the world is becoming increasingly visual. Even on more text-based networks such as Twitter (X), the addition of images can help with comprehension. Words will likely always be the foundation of knowledge, but visuals can help people better grasp and connect with information.

Creating visuals for technical documents presents its own set of difficulties. Oftentimes, technical authors have little to no expertise in creating visuals to complement written content. Visuals aren’t just nice to have, they are essential in helping readers understand the information being conveyed in words. 

There can be challenges to producing visual content, such as deciding which visuals perform best in which scenarios, selecting the appropriate tools and software, and understanding how to integrate them into your content.

This article is all about overcoming those challenges. It will explain the many types of visuals used in technical documentation, where they should be utilized, and the basic design principles for making effective visuals. Some of the best tools for creating visuals will also be reviewed, as well as how to avoid common mistakes that reduce the impact of visuals.

The Role of Visuals in Technical Documentation

Creating technical documentation can be quite a challenge. It involves translating complex concepts into simple language that almost anyone can grasp. Words alone are rarely enough, which is where visuals come in.

Good visuals capture readers’ attention without the need for lengthy text. They are great for raising awareness about the topic at hand, and they are often much easier to share and comprehend than plain text.

Visuals also boost engagement. The better an image, the more time readers are likely to spend engaging with the content, which leads to a better understanding of the subject matter. Visuals can assist in simplifying decision-making in a world of limitless distractions by presenting information clearly and simply. Images are processed faster and more effectively by the brain than words.

Whether you’re simplifying complex subjects or explaining tasks, note that a great visual is your best friend in making sure that the message is both understood and remembered.

Types of Visuals in Technical Documentation

There are a variety of visuals you’ll come across in technical documentation. Each type serves a unique purpose. Some of them are:

Diagrams: These are your go-to for explaining complex processes, relationships, and mapping out workflows. They are best used in guiding users through the flow of information and the interconnections between various components. Examples include flowcharts, block diagrams, and network diagrams.

This diagram from the WordPress open-source project shows which template files are called to generate a WordPress page based on the WordPress template hierarchy (source).

Illustrations: When you need to offer a detailed and thorough representation of information or objects, illustrations work best. They pop up everywhere from blog articles to technical manuals. Some of the more common examples include infographics, technical Drawings, and machine schematics.

This is Dennis Dawson's sketchnotes illustration based on Dennis Mortensen's presentation, "The Power of Product Screenshots in Your Help Documentation" (source).

Charts and Graphs are used when it’s time to present numerical data, track trends, or make side-by-side comparisons. You’ll often find them in reports and data-heavy technical documentation. Common examples include bar charts, line graphs, pie charts, and scatter plots.

Example of a bar graph from Chapter 4 of "Open Technical Communication" (source).

Pictures are a great reference that help to make text easier to follow. They are great at helping users identify, understand and follow instructions, as they are usually clear and concise. Think of screenshots, troubleshooting photos, location photos, and product photos as popular examples.

A screenshot from one of KnowledgeOwl's support articles (source).

Animations, GIFs, and Videos are extremely useful tools for engaging users, especially when there are complex step-by-step procedures to follow. They work great in software tutorials, training materials, and product instructions.

A GIF to illustrate the concept of Just-In-Time Documentation (source).

When developing technical documentation, it is essential to pick visuals that best represent the written information. Make sure to consider the complexity and skill level of the target audience to create visuals that both captivate and educate.

For those just starting out or tackling complex processes, animations and videos are your best buddies. When it comes to data and statistics, charts and graphics take center stage. When it comes to data and statistics, charts and visuals may be the best visuals to use. Illustrations are your allies when it comes to showing items and information in a thorough yet comprehensible manner. For providing reference and guaranteeing ease of use, images are the go-to, while diagrams are constant favorites for process explanations.

Always attempt to effortlessly merge your visuals with the associated text to make them genuinely shine. This not only improves comprehension, but also turns your documentation into a more entertaining and easily digestible resource.

Design Principles for Effective Visuals

For a visual to truly be effective, there are key design principles that are often referred to as “CRAP” principles: Contrast, Repetition, Alignment, and Proximity. Let’s dive into their meanings.

Contrast is all about creating differences and distinctions among the different elements in a design. It can be done through various methods such as color, shape, size, etc. The purpose is to guide the viewer’s attention to specific parts of the design that you, the designer, want to draw emphasis on. It ensures that essential information is communicated effectively.

An illustration that Dennis Dawson created in collaboration with Ellen Yang, Natalia Cebotari, and other design colleagues at Ripple for open source XRP Ledger documentation that is a good example of effective visual contrast (source).

Repetition involves maintaining consistency across different elements of the visual such as font, styles, or colors. This consistency provides a sense of familiarity with the visual and ensures that there is consistent branding. Repetition also gives structure and an air of professionalism to the visual.

KnowledgeOwl's Support Knowledge Base uses category icons that have a consistent and cohesive style.

Alignment focuses on the proper arrangement of the elements within the visual. It creates a sense of organization and order, bringing balance and structure to the overall design.

An illustration that Dennis Dawson created in collaboration with Ellen Yang, Natalia Cebotari, and other design colleagues at Ripple for open source XRP Ledger documentation that is a good example of visual alignment (source).

Proximity is a design principle that revolves around grouping related elements in proximity to one another. This grouping simplifies the understanding of the relationships between elements and makes the information more understandable.

"Principles of Design" poster from Paper Leaf (used with permission).

In addition to these design-specific principles, it's crucial to prioritize accessibility in your visuals. This includes including alt text for screen readers to scan and read; utilizing legible fonts and high-contrast colors; and avoiding white text on dark backgrounds. This ensures that your pictures are accessible to as many people as possible, regardless of their ability.

These principles are the foundation of visually successful and appealing designs. To make your visuals great, they must be simple and clear, allowing viewers to easily understand the intended message. All of these principles, when paired with clarity and simplicity, will produce excellent visuals.

Tools and Software for Creating Visuals

It makes a world of difference to have the correct tools and software to assist you in developing visuals for technical documentation. Some useful tools and software for this purpose include: 

• Microsoft PowerPoint remains one of the most popular and effective tools for creating visuals. It has great functionality like SmartArt which streamlines the process of bringing your visual content to life. Its flexibility also empowers the designer to make sure that key design principles are followed and that you have complete control over the structure.

• Adobe Creative Cloud may require a bit of training to fully harness its capabilities, but it is a powerhouse for all your visual-related tasks. Once you've learned it, you'll discover it to be a powerful tool for completing a wide range of visual projects.

• The Affinity Suite is composed of three powerful and complementary graphic editing programs: Affinity Photo, Affinity Designer, and Affinity Publisher. Many designers find Affinity’s software to be good alternatives to Adobe’s products.

• LaunchBrightly is a screenshot automation platform that automatically captures and enhances your product screenshots. It also runs an automated process to ensure that the screenshots in your technical documentation are always kept up-to-date.

• Canva, Visme and Infogram can be used to easily create infographics by providing beautiful and standardized templates, leaving you with the straightforward task of filling in essential information.

• Other useful tools include FIlestage, which is great for including feedback in documents of any kind. Skitch is a tool with a variety of choices that help with annotation, while Awesome Screenshot is a browser extension that allows you to take and edit screenshots in the browser.

In addition to these tools, the KnowledgeOwl content team has put together an article that introduces you to more tools for various aspects of creating technical documentation.

Common Mistakes to Avoid

Mistakes can happen when creating visuals. Being aware of potential mistakes and how to prevent them can help one produce great content. Here are some common mistakes and how to avoid them:

• Information Overload: Visuals can sometimes be overwhelming due to the inclusion of too much information. To avoid this, simplify the visuals by focusing only on key points and breaking down complex information into smaller, manageable parts. Consider creating multiple visuals if necessary.

• Poor Image Quality: Inconsistencies in image quality can be problematic, especially when readers access visuals on various devices with different resolutions. Ensure that your visuals are of high quality and that they remain clear and effective at different sizes and resolutions.

  Linus Says: Unlike raster-based images (e.g. JPGs), vector-based images (e.g. SVGs) are infinitely scalable, so they always render at a high resolution, regardless of the screen size or zoom level.

• Inadequate Testing: Testing is an important element in the visual creation process. Creators often fail to seek feedback from others or conduct testing with representative users to detect comprehension issues. In addition, failing to consider how graphics will be displayed on different screen sizes and devices might cause problems. To avoid these problems and guarantee that visuals are accessible and effective, thorough testing is required.

• Outdated Product Screenshots: Your product screenshots are the most immediate way customers identify what a help article is trying to help them resolve. If your product screenshots are outdated, it will erode your customers' trust and negatively impact core KPIs.

Mistakes are normal in the creative process, but learning from them and actively avoiding them is essential for growth and for consistently producing effective visuals that build an understanding of technical documentation.

Conclusion

When you decide to include a visual in your documentation, you must know where to place it for maximum impact. This should be decided during the documentation planning stage when the outline is developed. A visual without context is useless. A good visual has a clear purpose.

This article covered a lot about visuals, the best visuals to employ in various scenarios, design principles to follow when creating visuals, and common mistakes to avoid. It is important to pay attention to all of these details, as visuals can help to simplify concepts and improve readers’ understanding.