Corg.ly: Worth a thousand words

Charlotte looked at the comments Karthik had left on the draft. Some were easily fixable—a typo here, rearranging a paragraph there—but others would clearly need more work.

She spotted one comment in the overview she had written of Corg.ly architecture: “Not sure this describes data flow from the dog to the translation service to the user’s web application clearly. Is there more we can add or some other way to explain this?”

She reread the section line by line. Having spent some time away from the draft, she immediately saw Karthik’s point. It didn’t look like there was information missing, but she could see how most users would struggle.

She looked back at the research she had compiled earlier in the planning stages. All users they had profiled were short on time and needed to quickly assess how Corg.ly would integrate with their product. Words weren’t enough; she needed to find another way to quickly show how easily someone could slot Corg.ly into their product. Maybe it was time for a diagram…

When words aren’t enough

Your brain is reading this sentence. And this one. You may think you’re consuming chunks of text, but your brain is actually processing each word in this sentence as a shape and connecting these shapes to concepts and ideas. We recognize these parts of words to understand the whole.¹ Although reading may seem fast, it can be an incredibly inefficient process.

You may have heard the phrase, “a picture is worth a thousand words.” How long would it take you to read a thousand words? More than 13 milliseconds? A human brain can process an image at that speed, and even if you flick your eyes to a new image immediately afterward, your brain will continue to process the first image for longer than you originally spent looking at it.²

Single images require less cognitive processing, help your brain draw connections, and derive understanding much more quickly than written text. We also remember information better if it’s presented alongside images. When you hear information, you’ll recall only approximately 10% of it. If that information is accompanied by an image, however, you’ll remember 65%.³

Why visual content is hard to create

Like written documentation, the most effective visual content is something the reader barely notices. It doesn’t require them to stop in order to think or be aware of the fact they are consuming anything at all. When visual content works, it conveys information so quickly that the reader sweeps through their task. In the words of Edward Tufte, statistician, pioneer of data visualization, and all-round visual content expert, “Graphical excellence is that which gives to the viewer the greatest numbers of ideas in the shortest time with the least ink in the smallest space.”⁴

Knowing how our brains process images and text helps us craft better content, down to the typography we choose. Your brain finds it easier to process simple unadorned typefaces because it can more easily recognize the curves and strokes of each letter like the ones used in a sans serif font. Reading UPPER CASE TEXT LIKE THIS is difficult because the letters are the same height and size. Variety helps comprehension.

In Chapter 3, we discussed how using a variety of paragraphs, bullets, and numbered steps helps break up walls of text. Visual content is another way to bring variety to documentation and with great effect. In one study, readers who followed instructions with illustrations were 323% better at completing those instructions than readers with no illustrations to help.⁵

However, visual content is a supplement to and not a replacement for written documentation. Its purpose is to help increase understanding, and anything else is a distraction. “Every single pixel should testify directly to content,” says Tufte.⁶

If you’ve ever faced a set of architecture diagrams with too many arrows, labels, and layers, however, you know that visual content can quickly become more confusing than helpful. Visual content is often subjective. We often think we know what makes a good diagram or graphic helpful—but the most helpful visual content is what’s most useful for your reader. We know from Chapter 1 on user research that what we as creators like is often different from what our readers need.

It doesn’t matter whether you’re looking at screenshots, illustrations, graphs, videos, infographics, diagrams, or photographs. All visual content types, and all documentation including them, sometimes fail to help because of these issues.

Using screenshots

It’s sometimes useful to annotate screenshots to draw your readers’ attention to parts of the image. Blocks and arrows can help highlight parts of the image. Graying out other areas can help de-emphasize them.

You may be familiar with the options for alternative (or “alt”) text on images, including screenshots. Screen readers will read all of the findable text on a page. Writing alt text is one way to make your content more accessible to screen readers.

A better practice is to include a full description of what the image shows within the body of your main text. Leaving alt text blank tells screen readers to ignore the image. Instead, add a description of the content of the image as if the image wasn’t there at all. For example, “there is a small cog at the top of the menu” rather than “an image of a small cog at the top of the menu.” If you find this tricky to write, try explaining the image out loud—how would you describe it to someone?

Finally, never use screenshots as the sole source of critical information a reader may need, such as IP addresses or code samples. Readers often want to copy such samples or text for their own use and screenshots make that impossible.

Common types of diagrams

Diagrams can be an effective way to convey complexity without resorting solely to words, especially for help with visualizing processes.

Boxes and arrows

Box and arrow diagrams depict a flow from one item to the next. They appear frequently for good reason. When used well, box and arrow diagrams clearly depict a relationship or data flow between entities that would be difficult to explain with text alone.

Start by writing down the entities and the relationships you want to express. For example:

• Database ➤ API ➤ Front-end ➤ User

Choose a shape and line to denote each item and the relationship or flow you want to illustrate. Each entity should be represented consistently with a distinctive shape and design, for example, using square boxes exclusively to denote different apps (Figure 6-1).

Aim for minimal clutter. Do not cross any lines or arrows. Be clear whether a connecting line represents a one or two-way data flow, or whether it represents another relationship such as a dependency. If in doubt, add labels to the element or connecting line and add a legend that clearly defines what each element represents.

In Figure 6-2, the dotted lines and label help the reader understand which elements are microservices.

Flowcharts

Flowcharts guide a user from a start to a finish point and are particularly helpful for documenting processes.

Write down the process in full if it’s not already included in your written draft. Consider all of the possible directions or steps someone could take to achieve a result. Knowing how many options you need to include will help you know how much space you’ll need.

As with all diagram types, it’s important to be consistent. Flowcharts often use the same shapes to denote a type of action (Figure 6-3). For example, rectangles indicate processes and diamonds indicate a decision point. Any text within shapes must be legible with a large and clear font.

Swimlanes

Swimlane diagrams are particularly useful for situations with multiple contributors or acting parts. Much like a flowchart, they show a process from beginning to end. Each actor or contributor has its own lane, and each step of a process takes place in one of those lanes. In doing so, it’s easier to see at glance who or what is responsible for each step.

You can use horizontal or vertical lanes, or a mix of both. In Figure 6-4, each lane is a different “actor” in the flow. At each stage, the reader can see who performs which action.

Use the same consistency in process shapes and flows as you would for a flowchart. Make sure any connecting lines are clearly separated from the swimlanes themselves and your horizontal or vertical swimlanes are clearly labeled.

Drawing diagrams

Regardless of the type of diagram you choose, your objective is to simplify. Comic book artists have honed this skill. In his book, Understanding Comics: The Invisible Art, Scott McCloud explores how comics are incorrectly interpreted as conveying less information.¹¹ Instead, McCloud argues that by eliminating unnecessary detail, a comic’s true meaning is amplified. A good piece of art, or diagram, guides the user to understanding. To “simplify to amplify” as McCloud advises, you must keep your diagrams targeted to your users. Remember what you know about your audience and their task.

Illustrate only one idea per diagram. For example, show one level of abstraction in a system, one process flow, or a particular piece of logic. Figures 6-5 and 6-6 show the same process. The second is full of unnecessary detail that a reader may not need.

It’s okay to use multiple diagrams where splitting the information keeps things simple. Think about ways to walk your reader through your system or process. Overview diagrams can be a helpful addition to conceptual documentation, especially for readers new to your product or domain. Lower-level diagrams detailing data flows between specific microservices may be more helpful for reference documentation. Splitting information into chunks or layers helps to keep your designs targeted and provide the appropriate level of information to a reader at different points of their learning.

Creating video content

Beware anyone who tells you that videos are the solution to any software documentation problem. This isn’t to say that good video content cannot be a part of effective software documentation, but the path to success is littered with abandoned YouTube channels and footage of features last helpful to a user in 1998.

Video content can be useful when introducing a new concept. Marketers love it for the ability to condense an overview of a product or feature into a short time. Most technical writers are wary of videos. They are difficult to create, expensive to maintain, and most writers would struggle to prove they give value to users. Think about your readers: Would they really benefit from video overviews of your product? Could you provide a similar overview more quickly and cheaply with well-written documentation and some images?

If you do want to commit the time and money required for video production, find a professional. Video content is really, really hard to do well. Writing, filming, and editing video content always take longer than you expect, and you will need a professional’s expertise.

Much like static content, you must keep the accessibility of video to your readers in mind. Can all of your readers access the content using the hosting provider you have chosen? Is the video short enough to keep your readers engaged? Have you added captions to your video? Have you provided a full transcript with timestamps alongside the video? In addition to helping viewers who are deaf or hard of hearing, a published transcript can be indexed by search engines, making it more likely for your video to be found.

Remember that making changes to written or static images is much easier than amending a video. Plan ahead for your video maintenance: how long will it stay up to date? Are you prepared to reshoot or republish the video when you release a new feature?

Reviewing visual content

Visual content, no matter how few words it contains, is still content. That means you need to subject it to the same editing process covered in Chapter 4.

Never review the visual content in isolation. Check the text around it. Does its placement make sense in the text? Is it introduced properly? Does it move when you view your content on a mobile or larger screen and still make sense? Has it impacted your site’s performance?

Once you are satisfied it meets your comprehension, accessibility, and performance requirements, get it in front of colleagues for review. Remember that design is subjective and you still have the curse of knowledge. Your overfamiliarity with what you have documented makes it harder to evaluate your visual content objectively. In later chapters, we’ll explore ways to test the effectiveness of your documentation, including visual content.

Maintaining visual content

Chapter 11 discusses the biggest reason for most documentation failures: maintenance. Written text can fall out of date fast, but visual content can fall even faster. A single UI change can render your screenshots obsolete. A quick process change can mean that a single line in a diagram suddenly guides users incorrectly. A new feature can make a very expensive and well-produced video almost worthless.

Regardless of the format or tools you use to create an image, make sure you share the source files with others in order to make updates easy and possible.

Summary

Visual content conveys information more quickly than text, but it’s tricky to get visual content right. Make sure your images and your text complement each other. Screenshots have numerous specific requirements to make them useful. Don’t substitute a screenshot for copy-pastable text. Diagrams, labels, and colors all benefit from consistency and clean practice.

The next chapter guides you through taking the leap from creating and polishing content to putting a document out in the world for others to view.