Technology

Writing for a Busy World
Only Words That Are Read Are Worth Writing

by Peter Vasdi

The technical writing world is a dry but stable one: often essential, but not meant to be enjoyed. As a writer who has plodded many times through this dry world, I can’t help but hope that one day things will change; that one day others will actually want to read what I wrote.

A technical document making a best seller list? I can already hear the technocrats laugh. "Right", they say: "Private Protocols — a real hit.", "O/S Meets MVS — 10 million copies sold.", "The Office Analysis Story — everyone wants a copy", "The Mountains of Monitors — sold out and in its tenth printing", "RAMbo —...".

Well, it is possible, as evidenced for example, by the millions of copies sold under the "Dummies" name of computer manuals. To be a hit, technical manuals—like other products—need to appeal to their intended audience. Only documents that are easy to use and understand, that are visually attractive, and that meet the expectations of the audience will be read with pleasure.

To create a quality document requires considerable time and resources. In the past, documentation was viewed by most technical people as a mere afterthought—something that could be whipped up in a few days or even a few hours after the product had been developed. Unfortunately, this approach led to documents that were substandard, and therefore rarely, if ever, used by those who would have benefitted from the information they contained.

Keeping the Hope Alive

In recent years, some encouraging signs have been emerging within the documentation field. Organizations have recognized that in documentation, you get what you pay for. While few people would likely purchase a product based solely on the quality of the accompanying documentation, those same people may view the entire product as inferior if accompanied by poor documentation. Companies have consequently been devoting more resources toward their documentation efforts, with the aim of creating better documents.

Creating Fertile and Receptive Ground

As a documentation consultant, I feel that clients sometimes need to be reminded of the importance of their documentation, and of the effort that is required to produce good results. To this end, I have to make the client know that I have their best interests at heart. Specifically, I must familiarize myself with the client, and take into account many factors that may have an impact on my work. Such factors include:

• getting to know the client’s corporate culture and where documentation fits into their process,
• the tone the client prefers their documents to take,
• the client’s expectations about the appearance of the final product, and
• the text processing system the client prefers.

The most successful way of ensuring that these initial expectations are met is to have a meeting with the client, attended by all people involved, early in the project to discuss such issues.

Getting Your Audience Interested

The external appearance of a document is important. This is why most companies have learned to package their documents attractively. The industry knows that most people will judge (and buy into) a first impression. An attractive document that appears useful and non-threatening is the first step towards getting your audience interested. Other techniques that may be employed to generate interest include:

• An attractive cover that can focus attention onto the document itself.
• An informative but brief title that can identify the topic covered. A good title will appeal to some positive emotion—elicit a smile, or bring back a memory.
• A familiar symbol or logo that will help ease the transition between a potential reader and an actual reader.
• A short sentence or two on the document cover that explains what the document is about. Well written, and to the point, this statement should be enough for a person to pick the document up and open the cover.
• Once the document is opened, a table of contents that reads logically and that easily focusses the reader’s attention to a topic of interest.
• A document organization and page format that enables quick access to the section of interest.

Making Dry Things Interesting

Now that the audience has picked up the document, looked at the cover, browsed through the table of contents, and found the section of the manual that is of interest, the document must continue to maintain that initial level of interest. The challenge at this point it to make dry descriptions interesting. Some possible tools to accomplish this are:

• At the start of the section, state why the topic is useful and important.
• Scatter questions throughout the description. Information in a technical reference is meant to answer a series of questions. The whole document is written to respond to a need. It helps focus the reader’s attention if, from time to time, the question appropriate to the topic is restated.
• Restate the facts without using repetition. The very nature of technical documents is that they are not meant to be read from cover to cover. Readers usually want "the most pertinent information for the minimum amount of effort". Provide all the pertinent information in each section, and avoid making the reader cross-reference too many other sections of the document.
• Speak directly to your audience. This means using the first person, even though in most cases it will not be necessary to state the word "you" (for example, "You click on the OK button" would simply read "Click on the OK button").
• Where appropriate, lighten the mood through occasional use of humour.

If you follow these suggestions, will your document make you a millionnaire? Probably not. But at least you can be assured that you are providing a useful value-added feature to the product being documented, namely, enabling users to get the most from their new technology.