O'Reilly logo

Technical Writing by Phillip A. Laplante

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

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 reportsdiscussed 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 procedureseven 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.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required