Technical Writing
Lecture 4
Unit Two: Document Formatting and Design
• Quality Typography and Paper Structure
• Punctuation Marks
Unit Two: Document Formatting and Design
Quality Typography and Paper Structure
• Writing Coherent Documents
• Reviewing the Whole Document for Coherence
In looking for problems that need fixing, most writers look for
the largest, most important problems first, and then work on
the smaller, less important ones.
They begin by reviewing the document as a whole (for
organization, development, and content), saving the sentence
level concerns (such as grammar, punctuation, and spelling) for
later.
• Example P 68
Unit Two: Document Formatting and Design
• The title of a document is crucial because it is your first
chance to define your subject and purpose for your readers,
giving them their first clue in deciding if the document
contains the information they need. The title is an implicit
promise to readers: “This document is about Subject A, and it
was written to achieve Purpose B.” Everything that follows has
to relate clearly to the subject and purpose defined in the
title; if it doesn’t, then either the title is misleading or the
document has failed to make good on the title’s promise.
Unit Two: Document Formatting and Design
• Writing Coherent Headings
Headings, which are lower-level titles for the sections and
subsections in a document, do more than announce the subject
that will be discussed in the document. Collectively, they create
a hierarchy of information, dividing the document into major
sections and subdividing those sections into subsections.
• Revising Headings
Follow these four suggestions to make your headings more
effective.
• Avoid long noun strings. The following example is ambiguous
and hard to understand:
Unit Two: Document Formatting and Design
• Proposed Production Enhancement Strategies Analysis
Techniques
Is the heading introducing a discussion of techniques for
analyzing strategies that have been proposed? Or is it
introducing a discussion that proposes using certain techniques
to analyze strategies? Readers shouldn’t have to ask such
questions. Adding prepositions makes the heading clearer:
• Techniques for Analyzing the Proposed Strategies for
Enhancing Production
This heading announces more clearly that the discussion
describes techniques for analyzing strategies, that those
strategies have been proposed, and that the strategies are
aimed at enhancing production. It’s a longer heading than the
original, but that’s okay. It’s also much clearer.
Unit Two: Document Formatting and Design
• Be informative. In the preceding example, you could add
information about how many techniques will be described:
• Three Techniques for Analyzing the Proposed Strategies for
Enhancing Production
• You can go one step further by indicating what you wish to say
about the three techniques:
• Advantages and Disadvantages of the Three Techniques for
Analyzing the Proposed Strategies for Enhancing Production
• Again, don’t worry if the heading seems too long; clarity is
more important than conciseness.
Unit Two: Document Formatting and Design
• Use a grammatical form appropriate to your audience. The
question form works well for less-knowledgeable readers or
for nonnative speakers:
What Are the Three Techniques for Analyzing the Proposed
Strategies for Enhancing Production?
• The “how-to” form is best for instructional material, such as
manuals:
How to Analyze the Proposed Strategies for Enhancing
Production
• The gerund form (-ing) works well for discussions and
descriptions of processes:
Analyzing the Proposed Strategies for Enhancing Production
• Avoid back-to-back headings. Use advance organizers to
separate the headings.
Unit Two: Document Formatting and Design
• Writing Coherent Paragraphs
• There are two kinds of paragraphs: body paragraphs and
transitional paragraphs.
A body paragraph, the basic unit for communicating
information, is a group of sentences that is complete and self-
sufficient and that contributes to a larger discussion. In an
effective paragraph, all the sentences clearly and directly
articulate one main point, either by introducing the point or by
providing support for it.
A transitional paragraph helps readers move from one major
point to another. Like a body paragraph, it can consist of a group
of sentences or be a single sentence. Usually it summarizes the
previous point, introduces the next point, and helps readers
understand how the two are related.
Unit Two: Document Formatting and Design
• Structure Paragraphs Clearly
Most paragraphs consist of a topic sentence and supporting
information.
• The Topic Sentence Because a topic sentence states,
summarizes, or forecasts the main point of the paragraph, put
it up front. Technical communication should be clear and easy
to read, not suspenseful.
• The Supporting Information
• The supporting information makes the topic sentence clear
and convincing. Sometimes a few explanatory details provide
all the support you need. At other times, however, you need a
lot of information to clarify a difficult thought or defend a
controversial idea. How much supporting information to
provide also depends on your audience and purpose.
Unit Two: Document Formatting and Design
• Paragraph Length How long should a paragraph be? In
general, 75 to 125 words are enough for a topic sentence and
four or five supporting sentences. Long paragraphs are more
difficult to read than short paragraphs because they require
more focused concentration.
Example P 77
• Adding Transitional Words and Phrases
• Transitional words and phrases help the reader understand a
discussion by explicitly stating the logical relationship between
two ideas. The following Table lists the most common logical
relationships between two ideas and some of the common
transitions that express those relationships.
Relationship Transition
addition also, and, finally, first (second, etc.),
furthermore, in addition, likewise, moreover,
similarly
comparison in the same way, likewise, similarly
contrast although, but, however, in contrast,
nevertheless, on the other hand, yet
illustration for example, for instance, in other words, to
illustrate
cause-effect as a result, because, consequently, hence, so,
therefore, thus
time or space above, around, earlier, later, next, to the right
(left, west, etc.), soon, then
summary or at last, finally, in conclusion, to conclude, to
conclusion summarize
Unit Two: Document Formatting and Design
• Examples:
• Weak
• The project was originally expected to cost $300,000. The final
cost was $450,000.
• Improved
• The project was originally expected to cost $300,000.
However, the final cost was $450,000.
Unit Two: Document Formatting and Design
• This next sentence pair differs from the others in that the
weak example does contain a transitional word, but it’s a weak
transitional word:
• Weak
• According to the report from Human Resources, the employee
spoke rudely to a group of customers waiting to enter the
store, and he repeatedly ignored requests from co-workers to
unlock the door so the customers could enter.
• Improved
• According to the report from Human Resources, the employee
spoke rudely to a group of customers waiting to enter the
store; moreover, he repeatedly ignored requests from co-
workers to unlock the door so the customers could enter.
Unit Two: Document Formatting and Design
• Repeating Key Words
• Repeating key words — usually nouns — helps readers follow
the discussion. In the following example, the first version
could be confusing:
• Unclear
• For months the project leaders carefully planned their
research. The cost of the work was estimated to be over
$200,000.
• What is the work: the planning or the research?
• Clear
• For months the project leaders carefully planned their
research. The cost of the research was estimated to be over
$200,000.
Unit Two: Document Formatting and Design
• Sluggish
• The purpose of the new plan is to reduce the problems we are
seeing in our accounting operations. We hope to see a
reduction in the problems by early next quarter.
• Better
• The purpose of the new plan is to reduce the problems we are
seeing in our accounting operations. We hope to see an
improvement by early next quarter.
Unit Two: Document Formatting and Design
• Using Demonstrative Pronouns Followed by Nouns
Demonstrative pronouns — this, that, these, and those — can
help you maintain the coherence of a discussion by linking ideas
securely. In almost all cases, demonstrative pronouns should be
followed by nouns, rather than stand alone in the sentence.
In the following examples, notice that a demonstrative pronoun
by itself can be vague and confusing.
• Unclear
New screening techniques are being developed to combat viral
infections. These are the subject of a new research effort in
California.
• What is being studied in California: new screening techniques
or viral infections?
• Clear
New screening techniques are being developed to combat viral
infections.
Unit Two: Document Formatting and Design
• Writing Effective Sentences
• Structuring Effective Sentences
Good technical communication consists of clear, correct, and
graceful sentences that convey information economically. This
section describes some principles for structuring effective
sentences:
Unit Two: Document Formatting and Design
• Emphasize New and Important Information
• Sentences are often easier to understand and more emphatic
if new information appears at the end. For instance, if your
company has labor problems and you want to describe the
possible results, structure the sentence like this:
• Because of labor problems, we anticipate a three-week delay.
• In this case, the “three-week delay” is the new information.
Unit Two: Document Formatting and Design
• If your readers already expect a three-week delay but don’t
know the reason for it, reverse the structure:
• We anticipate the three-week delay in production because of
labor problems.
• Here, “labor problems” is the new and important information.
• Try not to end the sentence with qualifying information that
blunts the impact of the new information.
• Weak
• The joint could fail under special circumstances.
• Improved
• Under special circumstances, the joint could fail.
Unit Two: Document Formatting and Design
• Choose an Appropriate Sentence Length
• Sometimes sentence length affects the quality of the writing.
In general, an average of 15 to 20 words is effective for most
technical communication. A series of 10-word sentences
would be choppy. A series of 35-word sentences would
probably be too demanding.
Unit Two: Document Formatting and Design
• Avoid Overly Long Sentences
• How long is too long? There is no simple answer, because ease
of reading depends on the vocabulary, sentence structure, and
sentence length; the reader’s motivation and knowledge of
the topic; and the purpose of the communication.
• To avoid creating such long sentences, say one thing clearly
and simply before moving on to the next idea. For instance, to
make this difficult 40-word sentence easier to read, divide it
into two sentences:
The construction of the new facility is scheduled to begin in
March. However, construction might be delayed until April or
even May by winter weather conditions, which can make it
impossible or nearly impossible to begin excavating the
foundation.
Unit Two: Document Formatting and Design
• Avoid Overly Short Sentences
• Just as sentences can be too long, they can also be too short and
choppy, as in the following example:
Customarily, environmental cleanups are conducted on a “time-and-
materials” (T&M) basis. Using the T&M basis, the contractor performs the
work. Then the contractor bills for the hours worked and the cost of
equipment and materials used during the work. With the T&M approach,
spending for environmental cleanups by private and government entities
has been difficult to contain. Also, actual contamination reduction has
been slow.
• The problem here is that some of the sentences are choppy and
contain too little information, calling readers’ attention to how the
sentences are constructed rather than to what the sentences say. In
cases like this, the best way to revise is to combine sentences:
Customarily, environmental cleanups are conducted on a “time-and-
materials” (T&M) basis: the contractor performs the work, then bills for
the hours worked and the cost of equipment and materials. With the T&M
approach, spending for environmental cleanups by private and
government entities has been difficult to contain, and contamination
reduction has been slow.
Unit Two: Document Formatting and Design
• Focus on the “Real” Subject
• The conceptual or “real” subject of the sentence should also
be the grammatical subject. In the following examples, the
weak subjects obscure the real subjects.
• Weak The use of this method would eliminate the problem of
motor damage.
• Strong This method would eliminate the problem of motor
damage.
• Weak The presence of a six-membered lactone ring was
detected.
• Strong A six-membered lactone ring was detected.
•
Unit Two: Document Formatting and Design
• Another way to make the subject of the sentence prominent is
to reduce the number of grammatical expletives. Expletives
are words that serve a grammatical function in a sentence but
have no meaning. The most common expletives are it is, there
is, there are, and related phrases.
• Weak There is no alternative for us except to withdraw the
product.
• Strong We have no alternative except to withdraw the
product.
• Weak It is hoped that testing the evaluation copies of the
software will help us make this decision.
• Strong We hope that testing the evaluation copies of the
software will help us make this decision.
Unit Two: Document Formatting and Design
• Focus on the “Real” Verb
• A “real” verb, like a “real” subject, should stand out in every
sentence. A common problem in technical communication is
the inappropriate use of a nominalized verb — a verb that has
been changed into a noun, then coupled with a weaker verb.
Weak Each preparation of the solution is done twice.
• Strong Each solution is prepared twice.
• Weak Consideration should be given to an acquisition of the
properties.
• Strong We should consider acquiring the properties.
Unit Two: Document Formatting and Design
• Use Parallel Structure
• A sentence is parallel if its coordinate elements follow the
same grammatical form: for example, all the clauses are either
passive or active; all the verbs are either infinitives or
participles, and so on. Parallel structure creates a recognizable
pattern, making a sentence easier for the reader to follow. The
verb in the following examples are nonparallel because they
do not use the same verb form.
Nonparallel Our present system is costing us profits and reduces
our productivity.
Parallel Our present system is costing us profits and reducing
our productivity.
Unit Two: Document Formatting and Design
• When using parallel constructions, make sure that parallel
items in a series do not overlap, causing confusion or even
changing the meaning of the sentence:
• Confusing The speakers will include partners of law firms,
businesspeople, and civic leaders.
“Partners of” appears to apply to “businesspeople” and “civic
leaders,” as well as to “law firms.” That is, “partners of” carries
over to the other items in the series. The following revision
solves the problem by rearranging the items so that “partners”
can apply only to “law firms.”
• Clear The speakers will include businesspeople, civic leaders,
and partners of law firms.
Thank You For Listening
