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

From Where I Sit: My column in Voices of Central Pennsylvania, November 2010

My only experience with an earthquake was in the Silicon Valley of California. I was staring at my broken computer when the earth moved beneath me. The following day The San Jose Mercury News put the earthquake on page one because of its intensity and also contained an editorial on the importance of being prepared.

My home (wife, two daughters, two cats) was back in North Carolina. There I had worked in Research Triangle Park for two years (focusing on linking a computer to a telephone switch) had disappeared. Without warning jobs in documentation had become the moral equivalent of famine where two years previously had been feast. [At a Northern Telecom job interview I had been told being a technical writer had secured me a guaranteed income for life (gold watch and all)] .

At the same time as my gold watch turned into costume jewelry, my ability to walk disappeared. I had gone from being able to jog on the beautifully wooded track on the corporate campus, to being unable to stand without holding onto something, to tripping on my toes and dislocating my right shoulder.

An extensive search of databases showed San Jose, California, could not hire technical writers quickly enough. A longtime friend had extra room nearby and invited me to go west. I was hired immediately. I fell three times during a critical interview. My cane could not hold my weight. I had not yet acquired my first mobility device, a frontwheel drive scooter.

After my third fall, directly in front of my prospective boss’ feet, Vicki, who was in charge of the corporate quality assurance team, said, “Don’t worry. We have to hire you.” The reason I had to be hired was that the company, a global leader in computer wafer inspection devices, needed a writer for its new product which could predict when a wafer in the production process would be faulty and remove it from its production line on a timely basis. What the company had not prepared for was any safety orientation for disabled workers.

***

These details are relevant to the evolution of fire safety policies at Addison Court in downtown State College. They are relevant because first, until recently the idea of protecting the disabled and elderly from fire and other emergencies was low on our society’s consciousness. Second, limiting safety and access to one location and one building has long-term negative consequences to our country’s economy—an economy which to its detriment fails to make use of the talent of its disabled and elderly population.

R e g a r d i n g safety at Addison Court, a residence for 90 elderly and disabled individuals, where as a result of faulty fire alarms about two years ago, we learned from Steve Bair, fire director of Centre County’s Council of Governments (COG) and head of Alpha Fire Company, the proper way of evacuating a building made of brick with adequate sprinklers:

Do not evacuate. Wait for the fire company to come. Evacuation of disabled and elderly residents (in a multi-story building), especially when they have power chairs, wheel chairs, and the like, can induce panic.

More on this do not evacuate concept which the fire authorities refer to as “defend in place” later. It makes good economic sense to protect disabled and elderly individuals from dying or being hurt in a fire or in some other disaster. A larger question is whether this society has the will to pay for safety, the understanding of where safety belongs in our order of priorities, and the willingness to teach and implement concepts like “defend in place.”

The most recent available Census Department statistics for Centre County (based on a 2006-2008 estimate) shows a total population of a little more than 144,000; 45,000 residents are 45 years old and older. Nearly 16,000 residents range in age from 65 years to over 85. What is the cost to Centre County and society at large to keeping these 16,000 residents safe and productive if many of them require special safety procedures? Who should pick up the tab? IWe need to invest in quieter, gentler fire alarms so that residents stay in place until the fire trucks come.

Several subjects require elaboration on the voiceswepage.org webpage: direct your browser to future blogs on the following subects:

Administrative efforts to reduce panic.
The continuation of my meandering earthquake story and where it fits into a larger picture.
Plans to make Lady Gaga Fire Prevention Celebrity for Centre County.

—Joel Solkoff, author of The Politics of Food. For a continuation of themes raised in this column, see Joel;s blog at voicesweb.org.Tell me how you liked the photograph of Lady Gaga and an illustrated critique of her disability-related video Paparazzi.