Keeping the “Technical” In Technical Writing

Published in the February, 1997 issue of Blue Pencil

Of all the documents tech writers produce, user manuals for software products probably take the most effort. A good deal of information is required about the product. How do writers obtain the information they need about a product in order to write the manuals? The answer to this question seems to revolve around two schools of thought on how manual writers should do their jobs.

Students of the first school believe developers and/or subject matter experts (SMEs) should supply the bulk of the information to tech writers in some written form. The tech writer then collects, edits, and formats this information to create a finished manual. A minimal amount of interaction with the product is required by the writer. Students of the second school believe in the opposite of the first school: Developers should contribute a minimal amount of written information, letting the writers generate the bulk of information for themselves after gaining a thorough understanding of the product. I believe every tech writer responsible for writing user manuals should be a graduate of school number two.

From a project perspective, there are many good reasons why tech writers should become almost as knowledgeable about the product as the people developing it:

• developers can spend less time writing and more time developing
• writers do a better job of relaying product information to the reader when they have hands-on experience with the product
• writers will grow in capability, add value to project team and to the organization
• developers/SMEs need only review drafts for technical accuracy, which can be minimized in proportion to the writer's level of technical understanding
• writers have a better chance of meeting their deadlines

From a personal perspective, writers who take the writing bull by the horns rather than have snippets of text handed to them, are more likely to benefit from a positive growth experience:

• write with confidence and impart to the reader a level of understanding equal to the writer's
• become knowledgeable in the development process thus broadening the writer's experience base
• learn to ask questions, deal with personalities, stay focused, and most importantly, learn to listen

Making the transition from the first school to the second is not as difficult as you might think. The process for writing a user manual should begin as soon as the product's functional requirements are complete. A working outline of the manual can be developed based on the requirements document. As development proceeds, the writer should attend meetings and walk-throughs where functionality is an issue. The writer should also be aware of development's progress: As product sections are completed, the writer should begin learning their operations first-hand. Once learned, this knowledge can be transferred to the manual. The product's test team is also a good source for the writer. Testers always know what works and what doesn't.

This writing process requires the writer to become more involved earlier in the project. As the writer learns more about the product, more can be written; screens can be captured as they are completed. This kind of head-start and continuum of writing, learning, fact gathering, is far better than the traditional method of waiting until the product is finished, then making a Herculean push to write the manual.

As you can see this process also imparts greater responsibility to the writer. By definition technical writers are supposed to be people capable of learning technical concepts then writing about them for non-technical audiences. So, why depend on developers to write your drafts for you? Why not learn the technical aspects of the product for yourself? Think it's too hard? Perhaps you've chosen the wrong career path.