Technical Writing

C H A P T E R

2
Technical Writing Basics

Semester: 6th
Credit#: 2
2.1 Structure 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 into
sections of greater detail, and those sections into subsections, and so on, each at an increasing
level of detail.
The composition 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.
It is uncommon to go further than fourth-level headings in most technical documentation.
2.2 Positioning Your Writing
2.2.1 Know Your Audience
Before you begin writing, you must fully understand your intended readership and prepare to
align your work accordingly. for customer versus vendor, technical versus nontechnical
personnel, and government agency versus other entities.

2.2.2 Are You Talking to Me?

▪ First-person point of view: Autobiographies and many novels, describing a series of events in
which the writer is involved and In technical business communication
▪ Second-person point of view: procedures manual or user guide
▪ Third-person point of view: is preferred in accident or incident reports, descriptions of
experiments and tests, and in project postmortem reports. Disclosure of research findings is
almost always written in the third person.
2.3 Choosing the Right Words
2.3.1 Conciseness
Conciseness in writing is not easy to achieve. French Mathematician Blaise Pascal once wrote to
a friend: “I have made this letter too long because I did not have the free time to make it shorter”2
[Pascal 1656].
 2.3.2 Precision and Hedging

Example:
1- It is typical for some of the hydraulic fluid to escape from the housing, but this leakage should
be minimal.
2- It is typical for some of the hydraulic fluid to escape from the housing, but this leakage should
be less than one milliliter per day.
You can’t always replace hedging words with precision. Sometimes you can’t offer much more
than a guess. For example, consider a discussion of the likelihood of some event for which you
have no prior statistics, and not even a probability model for constructing predictive statistics.
This would be a case where hedging words are necessary.
2.3.3 Universal and Existential Quantification
One symbol, ∀, means “for all” or, equivalently, “always,” “universally,” and “completely,” and
many other variations on this theme. ∀ is called the universal quantifier. The other symbol, ∃,
means “there exists” and is called the existential quantifier. Both symbols are powerful notations
for making sweeping statements, but their use can be fraught with danger [Voas and Laplante
2010].
➢ All
➢ None
➢ Always
➢ Never
➢ Each

Universal and existential quantification should be used with great caution. Unless “all” or “none”
are demonstrably true, these words (and any of their equivalents) should be omitted.
2.3.4 Negatives
In technical writing, it is preferred to use the positive form of declarations, directions, and
instructions rather than the negative. For example, instead of writing “do not include” it is better
to write “exclude.” Similarly, instead of “do not permit” use “forbid,” and rather than “do not
allow” write “disallow.” The positive statements are more direct and promote the use of more
precise language.
the requirement should be written using “shall” statements rather than “shall not” statements.

Example:
The system shall permit access only to authorized users.
The system shall not permit access to unauthorized users.

In any case, you should write requirements using “shall” statements whenever possible, and when
clarity is not sacrificed. But “shall not” requirements may occasionally be preferred to their
“shall” equivalent form.

Example:
The system shall not harm humans.
The system shall do humans no harm.
2.4 Avoiding Traps
2.4.1 Clichés
A cliché is a lazy way to create an image. If you need to create such an image, do so through
effective writing.
2.4.2 Anthropomorphic Writing
It is not appropriate to project human feelings, behaviors, or characteristics upon animals,
inanimate objects, or systems. Such writing is called anthropomorphic, and it has a place in prose
and literature but not in technical writing.

Example:
8/23/2017, 3:11 PM EDT, upon running Test 3.1.2, the system failed miserably
the Internet is evil
2.4.3 Erroneous Heterographs
Two words are heterographs if they sound the same when pronounced but are spelled differently
and have different meanings.

✓ course: coarse
✓ facts: fax
✓ fourth: forth
✓ hire: higher
✓ hole: whole

The contraction “they’re” (meaning they are) also sounds the same as “their” and “there” and is
often used incorrectly in their place. Similarly, “it’s” and “its” are frequently misused. “Its” is the
possessive from of the pronoun “it,” while “it’s,” is the contraction of “it is.”
2.4.4 Opinion versus Fact

2.4.5 The Laziness of “Very”

Using the word “very” is a cheap way to try to amplify meaning. In the movie Dead Poets Society
(1989) teacher, John Keating, played by Robin Williams eloquently stated: “avoid using the word
very, because it’s lazy. A man is not very tired. He is exhausted. Don’t use very sad, use morose.
Language was invented for one reason, boys—to woo women —and, in that endeavor, laziness
will not do.”

Any form of “very” paired with another word should be replaced by a single equivalent word. For
example, “very large” could be replaced by “enormous” or “huge.” “Very loud” could be replaced
by “blaring,” “very heavy” by “weighty,” and “very clean” by “spotless.”
2.5 The 5 Cs of Technical Writing
As previously noted that technical writing is characterized by two features conciseness and
precision. These are qualities of the writing style and of the author(s) of the work.

1. Correct
2. Clear
3. Complete
4. Consistent
5. Changeable

Precision, one of the two special qualities of technical writing discussed in Chapter 1, is a
combination of clarity and correctness. I’ll discuss each of these five characteristics further.
2.5.1 Correctness
Correctness means that the information in the written artifact is grammatically and technically
correct. For example,
1. The automobile weight shall be no greater than 200 kilograms.
2. The automobile shall weight shall be no greater than 2000 kilograms.

2.5.2 Clarity
Clarity (or unambiguousness) means that each sentence, related groups of sentences, or related
sections of the written document can have only one interpretation.
2.5.3 Completeness
A technical document is complete if there is no missing “relevant” or “important” information.

The most powerful technique for reducing incompleteness is to have as many persons read the
material as possible.

In some technical writing, where subsequent versions of the document are expected, you can keep
track of missing information as it is identified and then add that material to the next version of the
document.
2.5.4 Consistency
The consistency of a document can take two forms: internal and external. Internal consistency
means that one part of the document does not contradict another part. External consistency means
that the document is in agreement with all other applicable documents and standards.

Internal and external consistency can be checked through reviews and can be repaired in
subsequent versions of the document as inconsistencies are identified.

2.5.5 Changeability

A document is changeable if the structure of the document will readily yield to modification. It is
obvious why changeability is an important quality of any technical document—the contents will
change as errors and omissions are identified.
2.6 Referencing
2.6.1 Choose the Right References
When selecting references to use in a technical paper or in any kind of technical writing, the use
of good judgment is essential.

Web referencing shall not be used a lot.

References that are too old, say more than ten years old for rapidly changing technologies, are
also inappropriate.

Your reference list should not include a preponderance of books (because books age quickly),
conferences (because these are not fully vetted), journal articles (because these are often too
theoretical), or Web references (because these do not have the same vetting and cognitive
authority as the other types of references). Indeed, a balance of these reference types is most
desirable. Your reference list says a lot about your familiarity with the subject matter, so use the
right mix of references.
2.6.2 Reference Styles
There are many ways to represent the references or bibliography for technical documentation. By
“represent” I mean the manner in which you list the author or authors, venue of publication, and
other pertinent facts that allow a reader to locate that reference.

There are many standard referencing styles. Scholarly and professional organizations publish
these styles—for example, the American Psychological Association (APA), the Modern Language
Association (MLA), the American Institute of Physics (AIP), and in the case of technical writing,
The Institute of Electrical and Electronics Engineers (IEEE).

It is often convenient to use bibliographic database software to organize and help format your
references. Common software tools for this purpose include ProCite, EndNote, and RefMan.