Technical Writing

11

2

Technical Writing Basics

2.1 Introduction

Although it is an unfortunate stereotype, engineers and technical profession-

als are often regarded as poor communicators. When I was an engineering

undergraduate student, a frequently hurled insult was “I couldn’t even spell

‘engineer’ and now I are one (sic).” Yet most of the engineers and scientists

who I know are well read and articulate, and can write effectively.

I am a Professor of neither English nor Communications, and this chapter

is not an introduction to basic writing principles. I assume (really, hope) that

you can write well enough. I won’t bore you with the more esoteric sub-

jects of introductory writing—for example, the “Harvard Comma”*—I am

just not that persnickety. For a great introduction to basic writing principles

and for guidance on punctuation, grammar, and structure, I recommend On

Writing Well [Zinsser 2006] and The Elements of Style [Strunk and White 2008].

These two books have profoundly inuenced and improved my writing.

What I cover in this chapter are some basic rules that will help you get

started with your technical writing.

2.2 Structuring Your Writing

Whether you are writing procedures documents, manuals, reports, or books,

it is conventional to organize your writing in a hierarchical fashion. Writing

is hierarchical if it is arranged as a cascade of sections or chapters at a high

level of abstraction, which in turn are composed of writing units (usually

sections) of greater detail, and those subsections into sub-subsections, and

so on, each at an increasing level of detail. The decomposition of writing in

this fashion is used to help organize and convey ideas from high level to low

level, that is, from abstract to concrete.

* That is, whether the last item in a sequence should be written as “lock, stock and barrel” or if

it should have the “Harvard comma,” written “lock, stock, and barrel.”

12 Technical Writing: A Practical Guide for Engineers and Scientists

It is not uncommon to use a hierarchical numbering scheme to indicate the

sections, subsections, and sub-subsections as follows:

1 First-Level Heading

1.1 Second-Level Heading

1.1.1 Third-Level Heading

1.1.1.1 Fourth-Level Heading

For this book, I have used a variation of this scheme in which the rst-level

heading is a chapter, the second level heading is a section, and so on; that is,

Chapter 1

1.1 Second-Level Heading

1.1.1 Third-Level Heading

1.1.1.1 Fourth-Level Heading

It is also possible to use different numeral types and fonts to denote higher

and lower lever sections.

I. First-Level Heading

A. Second-Level Heading

1. Third-Level Heading

a. Fourth-Level Heading

It is uncommon to go further than fourth-level headings in most techni-

cal documentation.

Regardless of the numbering scheme chosen, it is good practice to balance

the decomposition both externally and internally. External balance means

that if you organize your writing into major sections, then subsections, and

so on, then the relative numbers of each of these should be fairly uniform.

Internal balance pertains to the granularity of the decomposition; that is, the

relative length of the sections and subsections should be uniform.

For example, suppose you are writing some kind of systems requirements

document and you are using the hierarchical numbering scheme so that 1,

2, 3, … represent top-level sections with high-level detail; 1.1, 1.2, 1.3, … rep-

resent second-level sections (more detail); and 1.1.1, 1.1.2, 1.1.3, … represent

third-level sections with the most detail. You would expect that there would

be more subsections at low-level detail than at high-level detail. So, for a

hypothetical systems requirements document, if I listed the requirements at

each level, the resultant shape should be pyramidal (see Figure2.1a).