CXO

Get IT Done: Don't cut corners on technical documentation

Documentation should be as bug-free as an application


When lazy vendors use shortcuts to simplify their documentation processes, everyone—clients, end users, and IT support—suffers. I was unfortunate enough to come across just such a vendor recently, and the results from this vendor’s sloppy work were disastrous. Find out what happened and what you can do to avoid a similar fate.

Laziness cost this company a sale
As a contract technical writer for a Fortune 500 client, I routinely create two types of documentation. One type is the “road map” manual for end users of the application, people who are typically not very technical. The other type is the “how to support the app” manual for help desk analysts who do everything from install the app to answer common questions to troubleshoot common problems.

Recently, I was asked to learn how to use a commercial application for which the vendor provided a user manual in PDF format that was over 400 pages. My job: Write a shorter, sweeter version of the user manual.

Soon after I started working with the product, however, the vendor called and announced that it had a new Web-based front end for the client/server application.

My client placed me on the committee to evaluate the new version of the application, the Web interface. The big question: Is the new version worth the 10 grand or so the company would have to fork over for an enterprise license?

I surfed to the demo site and started whaling away on the new version of the application. I figured a brand-new, Web-based interface would be more intuitive than its older brother on the client/server side, and it was. Nevertheless, I asked for and received from the vendor a copy of the user manual for the Web application. It, too, was over 400 pages.

How do you read a software manual?
Like a lot of techies, I judge a user manual by a number of criteria. I look for a good table of contents, well-organized and easy-to-read chapters, and perhaps most important of all, a healthy index at the back of the book. I depend more on the index than on the table of contents when I’m looking for information about a specific topic.

I decided to drill down on a particular function to compare how the Web version handled it compared to the client/server version. I thumbed through the index and found the keyword I was looking for and then turned to page 287. The funny thing was, when I got to page 287, it was blank.

Then I realized that the index for the Web manual looked eerily familiar. I pulled out the user manual for the client/server version, turned to page 287, and lo and behold, there was the documentation I was looking for. The problem was that it was documentation for the client/server version of the application and not the Web-based version.

What the vendor did, and why it’s a bad thing
The vendor’s tech writers had used the user’s manual created for the client/server version as the template on which they based the user manual for the Web version of the application. The tech writers dutifully described the “Web ways” of performing functions common to both versions. They included screen shots to illustrate how the Web version looked and behaved differently from its client/server counterpart.

But they didn’t regenerate the index. The Web manual’s index was identical to the index in the old manual.

I know some of you are thinking, “Come on, Jeff, cut them some slack.” Some of you don’t even bother reading user’s manuals. If an application has an intuitive, user-friendly design, smart users can frequently jump right in and learn by clicking and doing.

But I can’t cut this vendor any slack. It’s a reprehensible mistake. It’s a pathetic oversight that made the vendor look extremely stupid.

“Gee,” I thought, “if no one bothered to double-check the manual for accuracy, I wonder how many bugs in the interface went undetected because of insufficient testing.”

When I reported that particular finding to my client’s software-evaluation committee, there was a loud, collective “Doh!” The vice president, the person who would have signed off on the purchase order, laughed out loud.

The vendor lost the sale.

What the vendor should have done
Technical documentation deserves the same amount of testing and scrutiny as the software it purports to document. When you update a how-to document, don’t just slap a new title page on the old user manual and assume no one will notice. I recommend that you make these rules part of your standard operating procedure:
  • Never use the template for an old version of the software as the basis for the new documentation. Start anew.
  • Always require the developer who created the software to review the documentation for technical accuracy, but don’t take his or her word for it. Have someone from the quality assurance department—or someone who will be using the software on a regular basis—start on the first page and work through every example and every illustration, making sure every step works as published.
  • Never publish the documentation without proofreading it. Hire a freelance editor if you must, but have a fresh pair of eyes scan the document looking for spelling and grammatical errors.

If you work for a software development company, if you write training documentation for end users, or if you document any application or process for any audience, follow these simple rules, and you’ll have a product you can be proud of.

Document your opinion
To comment on this column, or to share your opinion about the state of technical documentation, please post a comment or write to Jeff.

 

Editor's Picks

Free Newsletters, In your Inbox