Randell Prue
I can’t think of a more effective tool for a writer or editor than to sit down and test the document. Do it: Follow the instructions that are about to be published. When you sit down to describe what you experienced, the product will be better as a result. In research circles, anecdotal evidence is often discounted as worthless. Nonetheless, the retelling of my own experience has produced documentation that garnered both critical acclaim and a high degree of reader acceptance.
You can’t argue with success!
This article responds to one of the topics proposed for Corrigo — technical editor by accident. I don’t think that the circumstances I found myself in are unique, where the absence of a technical editor requires technical writers to take on the task themselves, with no standards defined and no job description.
How Did it Happen?
Hired as the only technical writer for the maker of hardware/software speech-recognition solutions on the so-called bleeding edge, I was solely responsible for the accuracy of release notes, user’s guides and installation manuals. I had access to developers, functional prototypes and finished product.
Over 14 months, the growth of the company left me at various times with up to five writers, no manager and no editor of any kind. My role was defined as supervisor, but had I not acted as editor and technical editor, the help desk, the company’s image and the usability of the product would all have suffered. The potential cost of certain errors was extremely high.
The Worst
The most serious error that was about to be published in the printed manuals and in our online help was a set of instructions to move or copy a portion of the system’s data to a different place in the filing hierarchy.
When I followed the instructions from the developers (the authors of the code), I succeeded in erasing the data to be moved, but I could not move the data. Under the right circumstances, the competitive edge that this error could have given to one of our competitors would be lethal.
I found out afterward that this error was introduced during the process of improving the software. The method described had worked in previous versions, and as a result of my testing, the method was corrected prior to release. Because the documentation had to be completed and sent to press before the correction to the product happened, I removed the erroneous instructions from the documentation. There were other ways of moving data within the system that did work and were accurately documented.
If a user of our system had ever erased data by following our instructions, we could reasonably have been held responsible for the cost of recovery. As you can imagine, recovery could include several temporary workers and/or overtime. Covering all these expenses could easily exceed the money earned by the sale of the system.
Not So Bad
Even if the error had had far less serious repercussions, it would nonetheless have created confusion, delays and a reduction in the quality of our service to our customers. My recommendation to try the instructions yourself demonstrates the process and mind-set that I recommend for all writers and editors.
Another incident involved a junior writer circulating a memo to all writers that the company’s main fax number had been changed and should immediately be changed in all manuals and documents. Here is where having an inquiring mind, which I consider essential to a writer or an editor, comes into play. When I heard about the new fax number, I asked myself why a company would change its fax number, making all stationery and business cards obsolete? In our case, I thought that it might have to do with telephone system integration, a major factor in the development of our product.
I investigated why the telephony aspect of our product might cause our fax number to change. I started with the front desk receptionist, who assured me that our fax number had not changed.
Two or three inquiries later, I discovered that the help desk had installed an additional fax machine. During the installation of our system at the client site, facsimile transmissions between the installer and the help desk were required. The installation process was accelerated by eliminating the delay caused by routing the faxes from the front desk to the help desk.
As a result of verifying the accuracy of the material to be published, all the bad stuff was prevented. All writers were instructed to ignore the change and to undo changes to the fax number. Additionally, the new fax number was added to the installer’s manual with an explanation of when and how to use it.
The Best
In independent benchmark testing, our documentation received a higher score than did any other component of the product, and was rated higher than any of our competitor’s documentation. Did I feel that warm, fuzzy feeling you get from a job well done? Definitely, but the tangible career progress that followed felt even better. In the aftermath I received an offer that my employer could not match and I could not refuse. This event resulted directly from accuracy and attention to detail.
On a regular basis, I made it a point to sit down with developers (a fancy name for software programmers) and have them show me how a feature or module worked. The experience was usually the same — the developer explains how it’s supposed to work — convinced that it will work as described because it worked under test before it was integrated and began to interact with other segments of program code.
“Would you mind showing me how that
works?” I would ask.
I could not count the number of times that this question resulted in a live demonstration of product failure, leading to correction and a better product. The best writers we had followed this same practice of verifying everything. When I left, the company was in the process of recruiting an editor. Not a technical editor. I think they believed that their quality assurance process and validation by developers was adequate. I believe otherwise. I believe that a technical editor (or a technical writer who does his or her own technical verification and editing) contributes to product quality and accuracy in a way that no one else is positioned to do.
Randall Prue is a freelance writer, editor and publisher. His web site, www.jacinet.com/~randall
, contains samples and links to published works. He can be reached by e-mail at randall@johnabbott.qc.ca.