Technical Writing

Technical Writing

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

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.

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.