The Value of Adding Images to Technical Documentation
by V Berba Velasco JR., PH.D.
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 , http://www.elispot-analyzers.de , http://www.elispot.cn ), a biotech company in Cleveland, Ohio.
| DISCLAIMER: The content provided in this article is not warranted or guaranteed by Developer Shed, Inc. The content provided is intended for entertainment and/or educational purposes in order to introduce to the reader key ideas, concepts, and/or product reviews. As such it is incumbent upon the reader to employ real-world tactics for security and implementation of best practices. We are not liable for any negative consequences that may result from implementing any information covered in our articles or tutorials. If this is a hardware review, it is not recommended to open and/or modify your hardware. |
More Online Business Help Articles
More By Developer Shed
 developerWorks - FREE Tools!
|
This demonstration gives you an overview of IBM® Rational® Build Forge Express Edition, a global offering that provides a framework to automate and execute software processes. Rational Build Forge provides a software assembly line that can support all of your tools, technologies, and platforms so you can achieve a repeatable, reliable, and traceable build and release process.
FREE! Go There Now!
|
|
|
|
Learn field-tested SOA principles, methodology, technology and implementation from the global SOA market leader - in a new e-book by an IBM SOA expert. Written by IBM Certified SOA Solution Designer Bobby Woolf, "Exploring IBM SOA Technology & Practice" is the ultimate insider's guide to SOA - a PDF e-book packed cover to cover with IBM's specific advice on how to make your SOA implementation a success.
FREE! Go There Now!
|
|
|
|
Effective governance for lean development isn’t about command and control. Instead, the focus is on enabling the right behaviors and practices through collaborative and supportive techniques. Hear from Scott Ambler on how it is far more effective to motivate people to do the right thing than it is to force them to do so. Learn how to form a lightweight, collaboration-based framework that reflects the realities of modern IT organizations.
FREE! Go There Now!
|
|
|
|
Learn to enable users to both rate existing animations and to combine existing animations into new snippets. This is the third in a series of three tutorials that chronicle the building of a site that enables collaborative discussion and animation building using Domino and OpenLaszlo.
FREE! Go There Now!
|
|
|
|
Build secure Web services with transport-level security using IBM Rational Application Developer V7 and IBM WebSphere Application Server V6.1. Follow this three-part series for step-by-step instructions about how to develop Web services and clients, configure HTTP basic authentication, and configure HTTP over SSL (HTTPS). This first part of the series walks you through building a Web service for a simple calculator application. You generate and test two different types of Web services clients: a Java Platform, Enterprise Edition (Java EE) client and a stand-alone Java client. You also handle user-defined exceptions in Web services.
FREE! Go There Now!
|
|
|
|
Visit IBM developerWorks to download a free trial version of IBM Rational Business Developer V7.1. Rational Business Developer offers rapid and simplified development of business applications and services through Enterprise Generation Language (EGL) tools, generating Java or mainframe solutions while shielding developers from technical complexities.
FREE! Go There Now!
|
|
|
|
Portfolio Management is about effectively managing portfolio value by aligning portfolio investments with business goals. This complimentary e-kit provides a collection of materials that can help you understand how IBM Rational enables and automates best practices for improved governance and clear visibility into portfolio and project performance across the entire IT project lifecycle.
FREE! Go There Now!
|
|
|
|
Learn how to do more with your reusable assets with the free Rational Asset Manager eKit. The eKit includes demos on how Rational Asset Manager tracks and audits your assets in order to utilize them for reuse. Plus you’ll find white papers and a Webcast that discuss the challenges of a Service Oriented Architecture and how Rational Asset Manager can provide quick and effective solutions.
FREE! Go There Now!
|
|
|
|
The discipline of assembling and delivering software is maturing beyond standard developer-centric compile/test software builds. The end-to-end software development lifecycle is emerging as the new focus moves “Beyond the Build.” Join this on demand webcast to learn about methods for streamlining software delivery and key capabilities of the IBM Rational Build Forge framework for automating build and release management in environments of any size.
FREE! Go There Now!
|
|
|
|
The unprecedented scope of a service-oriented architecture (SOA) initiative brings to the forefront a number of management and governance issues that were sidestepped in the past. The key to a successful SOA implementation is managing and governing activities throughout the entire SOA delivery lifecycle by ensuring that services conform to the needs of all of the business’s stakeholders. Learn how service lifecycle management allows the business to ensure that the process by which services are defined, created, tested, deployed, optimized and retired is manageable, repeatable and auditable.
FREE! Go There Now!
|
|
|
|
All FREE IBM® developerWorks Tools!
|
