Technical Writing


For the purpose of this page, we are discussing technical writing within industry, not technical content for mass-market audiences.

Businesses, universities, non-profit organizations, and government agencies need to document technical and scientific information. Skilled technical writers help prepare research proposals, environmental impact reports, and peer-reviewed journal articles. Technical documentation and specialized manuals are also important, especially when documentation is required for legal and regulatory compliance.

Technical writing employs different rules than other forms of writing. In an ideal world, technical writing should be:

  1. Clear - no questions about the meaning of any procedure described or fact presented.
  2. Complete - detailed enough to support itself, while citing any external sources.
  3. Correct - nothing is more important than accuracy in technical writing.
  4. Concise - keep it short, since people do not enjoy reading wordy manuals or journal articles.
  5. Compelling - as much as possible, technical writing should compel readers to follow any given advice or to act upon the information presented.

Unfortunately, reality is more complex than idealized guidelines can suggest. Thanks to legal mandates, as well as the fear of lawsuits, it’s not always possible to craft reader-friendly documents. There are also documents that are so specific to a discpline that the content would not be easily understood outside a small audience of specialists.

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 any accompanying condescension.

Clear

The “text” of technical documents includes various visual elements. Examples include charts, graphs, diagrams, and photos.

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 the content.

The challenge is to be clear while complying with external mandates placed on technical documents. One thing to remember is that most mandates are minimum content standards; if clarity requires a few more words or illustrations, then add them. Even the U.S. Supreme Court has ruled that government limits on medical warning labels do not limit how much information you can or even should provide. Clarity means you educate readers and help refine their understandings of information.

Clear Organization

A clear organization helps make a document usable for readers. Technical writing tends to be organized into small chunks of information. In a“chunky” document 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.

Front matter refers to the pages before the body of a document. These pages are sometimes numbered in lowercase Roman numerals, or not numbered at all.

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. Generally, the front matter allows a reader to anticipate the importance of content. The front matter conveys the order in which tasks should be completed.

Clear Text

Technical writing should be as clear as possible. 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?) Do all you can to avoid potential confusion.

Complete

Too often instructions and technical documents are incomplete. Because the technical writer becomes familiar with a product or process, it is easy for the writer to accidentally to omit “obvious” steps within instructions. Never assume anything is obvious when preparing a technical document.

Textually Complete

There is a basic guideline for composing a complete technical document: never omit information a reader might need. Before you can decide what information is necessary, you need to know about the likely readers of the document. Generally, the less familiar an audience is with the underlying technology or science, the more information that must be included within the documentation.

If you include too little background information, readers might be confused and become frustrated. Too much information risks boring readers, leading them to assume much of the document can be skipped over, with potentially horrible consequences.

Visually Complete

Illustrations, tables, and other visual elements are essential to most technical writing. Words alone are seldom sufficient to convey complex technical information. Each type of visual element has its own uses; do not waste space with a visual unless it communicates more clearly than text could.

Tables are particularly useful in technical documents. 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

Charts and graphs are good for demonstrating trends, but they can also be misleading. Visuals tend to “overstate” information, due to what is known as compression: scales based on too few periods. For example, a chart of sales over the last month do not always illustrate a long-term trend. Be cautious using visuals. We have prepared a separate guide to informational graphics.

Correct

Nothing damages a manual or online help more than inaccurate information. While the technical content is paramount, the overall quality of documents matters a lot to readers. If there are obvious grammar and mechanical errors, damage to credibility is unavoidable. Once a reader notices one error, he or she will question the quality of the entire document.

To verify technical information, you might have to consult with subject matter experts (SMEs). While many technical writers have scientific or technical backgrounds, no one is an expert in every technical field.

  • Verify information with subject matter experts (SMEs);
  • Check all contributed content, such as illustrations; and
  • Proofread every page — and have another person check them, too!

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. What is compelling varies by the type of technical document and its intended audience.

  • Safe operation of a device;
  • Safe completion of a procedure;
  • Proper maintenance of equipment;
  • Successful implementation of a process; or
  • Compliance with legal requirements.

You should never rely on necessity being sufficient to hold an 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.



Free Shipping on orders of $25 or more at BarnesandNoble.com

 





Sites Linked to Here…



Writer: C. S. Wyatt
Updated: 27-May-2014
Editor: S. D. Schnelbach