The process of writing technical manuals requires a writer to be concise and structured. For the sake of being consistent, customers and programs will require their manuals to meet the standards of specifications.
For the U.S. Army, Navy, and Air Force, you will likely have to comply with MIL-STD-38784. This document contains detailed instructions on the preparation of every part of a technical manual. For additional instruction, there is an appendix with illustrations of all the elements and how they should appear.
Likewise, the aerospace industry has its own specification. The ATA 100 specification is an enormous document that describes the proper way to document aircraft systems and components. Each area of the aircraft, such as electrical, communications, and auxiliary power, has its own chapter code.
Illustrations are another key element addressed by these specifications. Military manuals are not allowed to have photographs, for example. The way items are called out, how legends are used, and other aspects of graphics are defined clearly in MIL-STD-38784.
Writing software documentation presents different challenges. The old Digital Equipment Corporation produced an excellent guide for software technical writing called the Digital Style Guide.
Another excellent book for software technical writers is the Microsoft Manual of Style. This guide does a great job of describing the elements of a software user interface. It will tell you how to refer to radio buttons, checkboxes, and spinner controls in your program.
When you are working in certain industries or with smaller customers, there may not be any clear specification to follow. I would recommend that you examine the publications of other companies in the same line of business (suppliers and vendors) to see what their technical manuals look like. Or you can adapt one of the aforementioned specifications to the task, even though they may be overkill for smaller projects.
Specifications are, in most cases, a guide. You must deliver what your customer wants, even if it strays from the roadmap provided by the spec. While each manual is different, most of them have many of the same sections and pieces arranged in different ways. Just make sure the customer always comes first.
If you would like to make a comment, please fill out the form below.
