Technical Writing
Technical writing employs different rules than other forms of writing. Before discussing these rules, here is a list of what technical writing should be:
- Clear - no questions about the meaning of any procedure described or fact presented.
- Complete - detailed enough to support itself, while citing any external sources.
- Correct - nothing is more important than accuracy in technical writing.
- Concise - keep it short, since people do not enjoy reading wordy manuals or journal articles.
- Compelling - as much as possible, technical writing should compel readers to follow any given advice or to act upon the information presented.
Not an English Paper
Technical writing is unlike formal English essays and traditional business writing. For instance, the passive voice finds its way into almost every paragraph. In technical manuals many things simply “are” or “were” and it is almost impossible to make sentences active. Also, many manuals and other technical documents now use “you” in place of “one,” directly addressing the reader. Technical writers have learned that their topics pose enough challenges without accompanying condescension.
Clear
There are two forms of clarity in technical writing: organizational and textual. We believe organizational clarity is primary to the success of any technical document and deserves the same attention as text.
Clear Organization
A clear organization helps make a document usable for readers. Technical writing tends to be organized into small chunks of information: chapters have sections, sections have subsections, and “marginalia” is common. The elements of clear organization include:
- Headings, subheadings, and other clear typographical cues;
- Tables of content, lists of figures, indices, and other navigational elements; and
- “Chunked” text in short, easy to skim paragraphs.
The table of contents and headings within a document should parallel an outline of the document. If your technical documentation cannot be easily modeled as an outline, the document is insufficiently organized.
Clear Text
How can you make the text of technical writing clear? If you are not writing for a specialized audience, avoid jargon. Industry-specific terms or acronyms might flow from your mind into the word processor, but did you always know these terms? Imagine writing for readers with no exposure to the concepts presented.
Another issue of clarity in technical writing is the use of pronouns. Inexplicably, technical writers love pronouns. They cause a great deal of confusion for readers. (See? Are “they” the pronouns or the writers?)
Complete
Too often instructions and technical documents are incomplete. Because the technical writer becomes familiar with a product or process, it is easy to omit “obvious” steps within instructions. Never assume anything is obvious when preparing a technical document.
Textually Complete
Never omit information a reader might need.
Visually Complete
Illustrations, tables, and other visual elements are essential to most technical writing. Words alone are seldom sufficient to convey complex technical information.
Never underestimate the power of tables. If a text includes lots of measurements or other data values, tables might be easier for readers. Technical writers need to know when words are not the best medium for communicating.
Our sales in the East Region were up 15%; the West Region was up 17%; and the Central Region was up 16%. The actual units sales were….
versus:
Region Sales (K) % Inc. East 10.5 14.9 Central 9.5 16.0 West 11.5 17.1
Correct
Nothing damages a manual or online help more than inaccurate information. Once a reader notices one error, he or she will question the quality of the entire document.
Concise
People skim technical information. This means the document has to be organized as useful chunks of information that can be used immediately. Long descriptions, literary metaphors, and other attempts to write “literature” frustrate readers of technical documents.
There are exceptions when a document section can be longer and more detailed, but by organizing your document for ease of navigation readers can selectively read for depth.
Compelling
There has to be reason for the reader to use a document.
Compelling Content
What is compelling varies by the type of technical document and its intended audience.
Visually Compelling
The reality is that the more professional a document appears, the more seriously a reader will consider its content. Page design is an important part of technical writing. Books by designer Robin Williams are ideal for technical writers.
Usability Testing
Technical writing is not the same as writing short stories or poetry. You must make sure a document performs its assigned task.