Home
>
Writing
>
The Value of Adding Images to Technical Documentation

The Value of Adding Images to Technical Documentation

It's clich?, but true-a picture does paint a thousand words. This is an important message to remember when writing any sort of user documentation, such as an installation guide or an instruction manual. A document that makes judicious use of images and diagrams will be much easier to understand than one that is composed entirely of text descriptions.

I observed this first-hand years ago, when a junior programmer at one company was asked to update the software installation manual for their machine controllers. One of the first things he did was to strip away all the screen capture images, reducing the entire document to plain text. "These images are just silly!" he said. "They take up space, and they're just not necessary. I trust that anyone who reads this document will be smart enough to figure it out."

This turned out to be a huge mistake. The technicians who had to use the manual had a difficult time making sense of its instructions. They had to repeatedly ask for clarification, and one of them told me that the pure text descriptions were just too cumbersome to follow. They were fearful of using these instructions at all, knowing that a single misstep could lock the controllers into an irrecoverable state. It was a ugly situation all around.

The problem was that this programmer didn't try to make things easy for the users. For one thing, he failed to consider that some technicians were not native English speakers, and that they might struggle with the wording. More importantly though, this programmer expected too much from his audience. He wanted to reduce these instructions to their bare essentials, thinking that would be adequate. He failed to consider that even an intelligent, otherwise careful reader might be tempted to jump over instructions, or would gloss over some critical detail. This is a common pitfall when time is short, and when the users are confronted with pages and pages of bland text.

A few carefully chosen images, with suitable captions, can go a long way toward preventing that. When I saw that the junior programmer was stripping away all the screen capture images, I cautioned him against that. "These images may not be strictly necessary," I said, "but they help clarify a lot of details. For one thing, they show the user exactly which button to push, or which window to select. This makes the instructions much easier to understand, and reduces the likelihood of a human error." To this day, I wish that he had heeded my warning.

Were the users intelligent enough to understand the manual, as he claimed? Certainly-but intelligence is no guarantee against human error. Could the images have been construed as talking down to the user? Perhaps-but in my experience, sophisticated users seldom respond that way. Rather, most of them seem to understand the value that these images bring to the table. Perhaps it's because most of them know what it's like to be frazzled and pressed for time, and how easily important details can be lost in the text.

So remember-a picture paints a thousand words, and a single screen capture can be worth more than a dozen pages of text. It's a lesson that's worth learning.

V. Berba Velasco has a doctorate in Electrical Engineering and has been practicing his trade for nearly a decade. During that time, he has repeatedly found that good technical writing skills are almost as critical as good engineering skills. Dr. Velasco currently works as a senior electrical and software engineer for Cellular Technology Limited (http://www.immunospot.com), a biotech company in Cleveland, Ohio.

one time home cleaning Highland Park ..

In The News:

The Berkeley Humanoid Light (BHL) is a lightweight, open source humanoid robot that anyone can build using 3D-printed parts and off-the-shelf components.

Meta’s new AI chatbot is getting personal, and it might be sharing more than you realize.

A new threat targets both Android and iPhone users: SparkKitty, a powerful mobile malware strain that scans private photos to steal cryptocurrency recovery phrases and other sensitive data.

Thanks to a team at the University of California, Davis, there's a new brain-computer interface (BCI) system that's opening up real-time, natural conversation for people who can't speak.

Privacy risks are hiding in plain sight, as your personal data is likely being collected, tracked, and sold without your knowledge.

VenHub, a fully autonomous, AI-powered smart store just opened at the LAX/Metro Transit Center in Los Angeles.

A woman's Facebook account takeover reveals dangerous social engineering tactics and provides lessons on recovery, avoiding scams and enacting stronger security measures.

Shanghai engineers are using 432 walking robots to relocate a complex, preserving Shikumen architecture while creating space for a modern underground hub and cultural center.

Major healthcare data analytics firm Episource had a cybersecurity incident exposing 5 million patients' medical records and personal information in recent breach.

A new sophisticated PayPal scam sends legitimate-looking emails from official PayPal addresses, using phone numbers instead of links to convince victims to download remote access tools.

Fox News' AI Newsletter brings you the latest on this rapidly evolving technology.

The innovative Kara Pod device extracts moisture from air to create mineral-rich water and brew coffee, featuring UV sterilization and compatibility with Nespresso pods.

Gov. Hochul unveiled New York's nuclear power plant project to power a million homes, which faces permit challenges while promising jobs and a cleaner energy future.

SAFE introduces Aerie, an underground luxury bunker combining high-end living with advanced security, wellness amenities and interactive walls simulating panoramic views.

A Facebook scammer posing as Elon Musk tricked a victim with promises of a Tesla and $250,000, requesting gift cards that become untraceable once the codes are shared.

Experience hands-free golfing with the Robera Neo smart caddie that uses AI to follow you, navigate obstacles and carry your clubs with GPS course mapping.

Cybersecurity alert: 16 billion passwords exposed in massive credential database affecting major platforms. Protect your accounts with password managers

The innovative BeBot robot uses electric power to remove pollution from shorelines, covering 20-30 times more area than manual collection while preserving wildlife.

A new ClickFix campaign targets macOS users with fake Spectrum support sites, tricking victims with CAPTCHA failures to paste commands that install information-stealing malware.

AI-powered autonomous trucks from Plus Automation are being tested across the U.S., Europe and Asia to solve logistics challenges while facing regulatory hurdles and labor concerns.

Your health information might feel private and secure with your doctor, but the reality is far more complicated. Data brokers collect a wide range of sensitive health data, from diagnoses and prescription details to personal identifiers, and sell this data to marketers, insurers, and other third parties.

Kepler Robotics has officially introduced its Forerunner K2 "Bumblebee" humanoid robot at the SAIC-GM automotive plant in Shanghai, marking a significant moment in the real-world deployment of advanced robotics.

Scammers never seem to be running out of new ways to try and get their hands on your money – and lately, they've been getting sophisticated.

Thirty people were injured and killed, though the exact number remains currently unknown, when a suicide bomber blew himself up in a Damascus church.

Unexpected password reset alerts signal potential hacking attempts or phishing scams. Learn how to respond and establish stronger security measures for your accounts.

The Value of Adding Images to Technical Documentation

Writing