Technical Writing

121

6

Technical Reporting

6.1 Introduction

Technical reporting documents have much in common with their business

counterparts but there are important differences. The former can be distin-

guished by a higher concentration of mathematics, data, formulae, and tech-

nical jargon; a need for greater precision; a higher attention to detail; and

the likely inclusion of procedural descriptions. “Technical reporting” is also

slightly different from the “technical reports” discussed in Chapter 4. The

latter is a kind of archival writing, although informal, for mass consumption

and reference. Technical reporting, conversely, refers to internal documents

or reports for customers, agencies, or management that are considered con-

dential, proprietary, or classied.

As noted in Chapter 1, technical reporting includes the following classes

of documents:

• Progress reports

• Feasibility studies

• System and software design and architectural specications

• Proposals

• Facilities descriptions

• Manuals

• Procedures

• Planning documents

• Environmental impact statements

• Safety analysis reports

I would also include strategic plans and bug reports to this list. In this chap-

ter I discuss and provide examples for some of these document classes.

122 Technical Writing: A Practical Guide for Engineers and Scientists

6.2 Technical Procedures

Technical procedures are descriptive documents that include step-by-step

instructions for assembling, processing, or organizing things. A procedures

document should contain the following (as applicable):

• Purpose of the procedure

• Safety information

• Preconditions—what must be true before the procedure is conducted

• Qualications of those who will conduct the procedure

• List of materials needed

• List of materials

• List of tools

• Step-by-step instructions

• Post conditions—what will be true if the procedure is followed

correctly

• Troubleshooting section

• List of frequently asked questions

The key to writing procedures manuals is to assume the reader is a

novice, or to document your assumptions about the previous knowledge

or experience needed. There is a special burden on the writer of tech-

nical procedures—even the smallest mistake can lead to catastrophe.

Therefore, you need to have both experienced and naïve colleagues test

your written procedures.

The wife of a former student recently published the delightful Unofcial

Harry Potter Cookbook, in which she gives recipes for foods mentioned in the

Harry Potter books [Bucholz 2010]. My student described to me the com-

prehensive recipe testing that his wife had conducted—preparing recipes

repeatedly and varying the ingredients slightly each time to simulate a

measurement error. She noted the sensitivity of the food to these errors and

adjusted the recipes accordingly. The author showed great diligence and care

in testing and revising her cookbook, setting a wonderful example of what

you should do in writing technical procedures.

Here are a few excerpts of technical procedures that I have written.

6.2.1 Vignette: PC Repair Book

When I was nishing my PhD, I decided to make some extra money by starting

a personal computer (PC) maintenance and repair business. After six months,

I had depleted most of my savings because I was not a savvy businessman,

but I did learn a great deal about PC maintenance and repair. I converted this

knowledge into a “how-to” book lled with technical procedures.