Time has changed, not reality.
“Put It In Writing-But Clearly — Software makers should help writers and artists create user manuals that are easy to understand”
BYLINE: Joel Solkoff
SECTION: FINAL WORD; Pg. 95
LENGTH: 728 words
When I left Washington nearly five years ago to take an exciting position in high-tech Research Triangle Park, N.C., many friends told me horror stories about the manuals they had received with software.
My new job was in telecommunications. I thought that because I was writing user manuals for expensive computerized switches, my employer would want me to make the manuals understandable. I was mistaken.
More recently, I worked on an object-oriented software development project. My job was to read the documentation the software designer had produced and rewrite it in plain English so that technicians in the field could understand how to load and use it.
“Don’t Bother”
I was told, however, that if I actually took the time to read and rewrite the documentation, it would delay production of the product manual. There had been little attempt to plan the process to ensure timely delivery.
Instead, management resorted to exhortations: Don’t bother to read about each product feature, just cut and paste from the software designer’s information. And don’t waste valuable time rewriting.
Technology suppliers today are under great pressure to rush new products to market. As a result, the way documentation is produced may cause these companies serious problems. Vendors that make complex software and hardware products should make the products as easy as possible to use. In some cases, such as sophisticated telecom switches, these products may compete with technology that is less sophisticated and that requires little documentation.
Producing decent documentation is not difficult. There are only a few steps to follow: Ask the customer what is needed. Produce it. Test it. Ask the customer if the documentation meets the requirements.
As simple as this process is, it is seldom followed. Computers and communications equipment buyers are told what they will get. An occasional, unmethodical survey is conducted to support the product manager’s choice of documentation. Useful modern marketing techniques such as focus groups seem beyond the ken of companies intent only on getting something out the door.
In addition, writers are often asked to translate unintelligible techno-jargon without first talking to the software designers, all because the designers aren’t allocated the time to make a discussion possible. Editors often don’t know enough about the subject matter to ask the questions that would make the documentation more understandable.
Diagram artists also complain about how poorly their skills are used. A recent editorial in Computer Artist lamented “relentless production schedules that often do not allow a reasonable amount of time to think about the art and the message it conveys.”
Finally, many product managers make the mistake of not even bothering to read the documentation that accompanies the products they worked so hard to produce.
These problems exist whether documentation is produced as printed manuals or in electronic form.
Contracts Over Customers
The big question is whether, in a period of cost-cutting, technology companies are willing to pay the price of educating their employees about the products they sell.
The second question is whether the companies even know how to do so. To cut costs, many are switching to contractors for their documentation. Technical authors work for agencies that contract with the company and farm out the work. These agencies could take responsibility for the manuals they produce, but their primary focus is on getting new contracts, not customer service.
Our high-tech businesses thrive on complexity. But unless they improve the quality of their documentation, they may endanger their ability to continue selling the sophisticated products that distinguish them from the competition.
Given the choice between a product that works intuitively and one that has difficult-to-read, often incorrect documentation, many customers will make the obvious choice.
–30–
Joel Solkoff is [was] a senior technical writer in Durham, N.C. Published July 3, 1995
Final Word [the section of the magazine in which this appeared] is a forum for professionals with opinions on information management. Your contributions are welcome. IW cannot return unsolicited manuscripts. Please send submissions to: InformationWeek, 600 Community Drive, Manhasset, N.Y. 11030