Technical Writing Notes
Dave Custer
Schedule
August 9: Overview
Introductions and Expectations
Writing: product & process
Product:
beginning, middle, end
unity, transition, development
common structures
Process: activities and habits
Description (exercise)
Proposal and Report Structure
August 10: Merging Process and Product
Grouping Logic (exercise)
Transition Words (exercise)
Transitions (exercise)
August 23: Graphics & Individual Conferences
Word Level Troubles (exercise)
Workshop
Graphics (exercise)
Conferences
August 24: Individual Conferences
TBA
Conferences
July 9
1
Expectations
It takes about 10,000 hours to become an expert writer.
In three weeks, you can expect to:
Progress a little along the curve
Gain confidence in your writing
Better know where you are headed
I need to know the specific writing concerns you have.
Writing: The Big Picture
Writing is both a noun and a verb.
As a noun, writing is a product, the written text. It is governed by convention,
from grammar rules to cognition rules to reader expectation.
As a verb, writing is a process, the series of activities writers engage in to produce
text. And the habits that guide the activities.
The secret to good writing is a combination of both process and product. The author must
know the reader’s expectations and craft the text accordingly.
July 9
2
Complexity:
Technical writing is an exercise in managing complexity, and technical writing
conventions exist to help with this management. (From Markel, Technical Writing)
* Jargon and abbreviations:
* Graphics (tables, graphs, figures):
* Equations:
* An emphasis on function over entertainment:
* The document is not meant to be read cover to cover:
* The document is useful only to a very narrow audience:
* The document is highly operational:
My addition to this list: for the most part, technical documents have clear deadlines. The
product must ship with the documentation; the conference paper must be submitted in
time to be published.
Complexity management requires design strategies; some commonly applied to technical
writing are described below:
* Simplification: Like the force, simplification has a light and a dark side. The
improper use of simplification is to ``water down,'' to remove relevant detail from a
perfectly good idea just to make the idea easy to express.
* Prioritizing: If the project is large, the most important aspects should be dealt with
first.
* Practice/Iteration: Iteration is important because the drafting process transforms the
idea as understood by the author into an idea that can be understood by the reader.
* Structure: Structure implies a hierarchy of elements and connection between all the
elements. Further, all the elements must add together to produce more than their mere
sum. For technical documents, structure increases the ease of finding and absorbing
information.
* Planning: Louis Pasture says, “Chance favors the prepared mind.” I say, “Only
prepared minds should write longer documents.” Planning is the definition or
organization of structure. Setting out to write a longer document without planning is a
waste of time. First, you will write yourself into a hole. Then your options are to fill in
the hole and start all over again or to dig deeper. Sometimes, you need to dig a few dead
end holes before you really get started, but, even so, you need to plan to leave yourself
enough time to practice digging.
* Abstraction: Distilling the essence of experience takes vast quantities of disparate
experiences and boils them down into a model of how the universe works. Abstraction is
a very effective method of simplification.
* Collaboration: If one person can do a whole project, the project doesn't qualify as
complicated. Complicated projects require the collaboration of several people.
July 9
3
Process
The recipe looks simple:
brainstorming
outlining
research
start writing
think-write-read-think-write-read
finish
Good writers go through cycles of writing, reading, thinking, and rewriting. The
frequency of the cycles and the focus of the rewriting vary from author to author. ESL
students cycle at the word level; each word is typed, checked for spelling/agreement, and
corrected before moving on. Some authors type entire paragraphs or pages before reading
them over. There is no “correct” recipe that works best for everyone. If how you write
works for you, continue; if not, try to change your writing habits.
Habits the author can control:
* Attention to detail. Pay less attention in early drafts. Proof read in later drafts.
* Work on multiple documents simultaneously. When stuck on one, switch to writing
the other.
* Work on different aspects of a document simultaneously. When stuck on the text, fix
a figure instead.
* Got writer's block? Force yourself not to use the delete key.
* Work at different times of the day.
* Learn your own bad habits. Has every English teacher and thesis advisor associated
red ink with your pronouns? Then be sure to scrutinize your pronoun usage. Can't spell?
Learn to recognize the words you butcher regularly.
* Start writing the middle of your document. The abstract is difficult to write; your
method section is liable to be easier. Description is relatively easy too.
* Leave yourself enough time to write well.
* Avoid binge writing the evening before the document must be finished.
* Stop writing for at least three days. You can do so if you've left yourself enough
time.
* If you are a perfectionist, suspend disbelief. Documents are never finished, only due.
* Decide at the start how perfect a document must be. Recognize this threshold and
desist from writing further.
The author's ultimate goal is to cultivate writing habits that make the reader happy. This
happy event occurs only when the author recognizes the discrepancy between a draft and
what the reader wants.
July 9
4
Some Writing Trajectories for Comparison:
Monitor your progress and know how good your document must be. If each revision does
not get you closer to finished, pinpoint your audience and purpose.
Don’t write like an undergraduate.
Two successful strategies. Pick a strategy that fits you best.
July 9
5
Product
Beginning, Middle, & End:
Text is linear and finite. These geometrical constraints imply that text has a beginning, a
middle, and an end. Readers expect the boundaries to be deliniated. Many grammar and
style guidelines make these boundaries clear.
thisiswhathappenswhentheauthordoesnotmaketheboundairesclear
When the boundaries are not clear, the reader can make sense of the text, but only after
investing significant effort into recreating these boundaries.
Unity, Transition, & Development:
Authors design documents. All the parts must connect. All the parts are focused on a
purpose. The whole exceeds the sum of the parts. Without unity, transition and
development, a document is merely a laundry list; the reader can only remember 5 things.
The design task is akin to fitting a jigsaw puzzle together so the reader sees the big
picture.
More on product tomorrow. Please read The Science of Scientific Writing,
(http://www.amstat.org/publications/jcgs/sci.html) for tomorrow’s session.
Common Structures:
Narration: Time is linear; text is linear. Stories are easy, but the moral may be unclear.
Procedure: Easy if the process is linear. Design the linearity into the process?
Grouping: Reductionist thinking. Making sense of the laundry list. More tomorrow.
Definition: Separating out one grouping element and discarding the rest.
Compare/Contrast: Beware of the ping pong match.
Cause/Effect: The story is easy: before => after. Authenticating the mechanism is hard.
Description:
Purpose defines which detail is included
Form often matches function
Sometimes, use the structure of the thing to structure the text
Metaphor
July 9
6
Description Exercise
Below is a draft of a technical report that describes a novel use of the Leidenfrost
Phenomenon. Pretend that you and your colleagues are writing this report. Your next task
is to write the first background paragraph that describes the Leidenfrost Phenomenon. I
encourage you to provide an overview and then break the description into parts. In the
body of the description, emphasize the efficiency of the gliding, the straightness of the
trajectories, and the simplicity of the motion (no moving parts). Dwell on these aspects
because they are important to your application. If you find that other aspects of the
phenomenon are important, by all means include these additional emphases.
A Leidenfrost Propulsion System for Titan Microprobes
Abstract:
A Leidenfrost drive system has been developed to provide a reliable, low cost propulsion
system for scattering Titan-lander remote micro-sensors. Computer simulations based on
momentum transfer and velocity proportional drag confirm project feasibility, and energy
analysis of surface tension and evaporation places limits on droplet size and sensor
geometry. A working prototype demonstrates proof of concept, but also shows the
importance of surface roughness, which limits the drive to surfaces with an Gaussian
RMS roughness measure less than 1% of droplet radius.
Introduction:
The low friction environment of Saturn's moon Titan makes the use of vehicular surface
sensing probes like the Pathfinder Rover untenable. The possibility of encountering
methane lakes further reduces the utility of roving vehicles....
Solutions must be robust....
Our solution combines micro-sensor technology with a novel Liedenfrost propulsion
system.
If you like, write different concluding sentence to the introduction.
Background:
The Leidenfrost Phenomenon was first studied in 1733 by Leidenfrost....
*** Fill in a description of the Leidenfrost Phenomenon, based on your observations.***
The Leidenfrost Phenomenon is explained by a model developed by Liedenfrost and
more recent researchers 1,2,3. In this model, the droplet goes through 4 distinct phases:
pool boiling, partial film boiling, stable film boiling, and propulsion boiling. Each phase
must be modeled....
Methods:
This project has 4 parts: modeling the friction, heat exchange, and momentum transfer of
the propulsion system, modeling the micro sensor's surface tension adhesion,
construction of prototype, and testing of prototype…
July 9
7
Proposal and Report Structure
Just a few thoughts in light of process and product:
The proposal is an odd document because it has no end. Most readers get no further than
the summary, so the summary must embody the entire enterprise.
Most summaries fail because they fail to identify a problem; identifying an area of
research or a hunch is not enough.
Try to keep the verb tense in the present; avoid the subjunctive voice. If your proposal is
well written and if your research goes as you expect, your proposal should appear word
for word in your report.
Reports have abstracts. Abstracts have 4 pieces of information: problem, solution, results,
conclusion. If you must, include half a sentence of context information, especially if your
audience is varied or your work interdisciplinary.
July 9
8
Drafting: Merging Product and Process
Writing is difficult for two reasons:
Text must conform to many constraints.
Text must make sense to both the author and the reader.
Bob hit Bill. He went home.
Pronouns are an example of this mismatch at the word level. The author saw the fight and
knows who went home. The example makes complete sense to the author. The reader
does not know who went home. The secret to correcting this mismatch and satisfying
convention is revision.
(For amusement: Trichloroethylene (TCE) is a ubiquitous example of the dense
chlorinated hydrocarbons, a family of organic liquids that have recently received great
attention from environmental professionals because they are highly toxic and
carcinogenic and are capable of persisting for long times in an aquifer and contaminating
large volumes of groundwater. In this exmple, the reader knows the antecedent from
context.)
Sometimes, writing is difficult due to a lack of familiarity with conventions of grammar,
style, and punctuation. If such unfamiliarity is a problem, brush up on your weaknesses.
Learn to recognize the rules and their exceptions. When in doubt, pick a convention and
stick to it.
The following pages are examples of text in various states of ill repair followed by
possible revisions.
July 10
9
Example 1: Developing Grouping Logic
2 A Theory of How Camming Devices Work
2.1 Model I
friction/angle relationship, log spiral geometry, range/holding power tradeoff, failure
modes
2.2 Model II
contact area estimates, onset of shear yield, strength/holding power tradeoffs, failure
modes
2 A Theory of How Camming Devices Work
To understand camming device (CD) performance requires a succession of models. The
first, is highly theoretical that assumes that the actual materials that compose the CDs are
perfect. An understanding of why these devices work, its shape, and the critical geometry
lead to an understanding of how they work. To this first model, an understanding of
material properties can be added. Because materials are not perfect, the second, improved
model explains why devices fail. Precisely the knowledge the climber needs to know
2.1 How CDs Work
As a first approximation, a CD can be modelled as a rod...
2.2 Failure Modes
Because the first model presumes that cams are perfectly strong...
2 A Theory of How Camming Devices Work
A succession of two models is used to develop an understanding of camming device
performance. The static model, assumes that the materials that compose the camming
devices are perfect -- perfectly rigid and strong. This static model provides a basic theory
of why cams work, defines the cam's shape, and determines the parameters that limit
frictional holding performance. The dynamic model builds on the static model by
additionally taking elasticity and shear yield into account. The dynamic model provides
estimates of the deformation and shear loading that produce skidding failure. Both
models must be taken into account to evaluate the overall performance of a camming
device.
2.1 The Static Model -- Explaining How Camming Devices Work
As a first approximation, a camming device can be modeled as a rod wedged or
“cammed” in a parallel crack as shown in Figure...
2.2 The Dynamic Model -- Materials Failure Modes
Because the first model presumes that the cams are perfectly strong and do not bend or
deform when weighted, it does not take into account the properties of the materials from
which cams are...
July 10
10
Example 2: Grouping Logic and Surprise Transition
All of these studies used MR images taken at only one time, some time after the onset of
the disorder. This made it difficult to estimate if the acquiring of the hippocampal lesion
was a result of the traumatic event experienced by the PTSD subject, or if a hippocampal
lesion was existent before the occurrence of the traumatic event and it was actually a
predisposing factor, facilitating the development of the PTSD. Also, the thickness of the
MR images used in these studies was to great to allow extremely precise volumetric
analysis. When 4 or 5 mm slices are taken the shape of the traced hippocampus is only a
poor approximation of the real hippocampus. The accuracy of the shape traced increases
with the decrease in thickness of the MRI slices - the thinner the slices, the more accurate
the shape of the region of interest and, therefore, the closer the volume obtained for the
region of interest to the actual volume.
a rewrite
Previous studies lack both the temporal and spatial resolution required to detect the
cause/effect relationship between PTSD and brain structure volume. MR images were
taken at only one time, some time after the onset of the disorder. Without a sequence of
images, it is impossible to determine whether a hippocampal lesion is a result of the
traumatic event experienced by the PTSD subject or whether a hippocampal lesion has
been existent before the occurrence of the traumatic event and might actually a
predisposing factor, facilitating the development of the PTSD. Additionally, the scanning
accuracy of the 4 or 5mm slices used in these studies provides a poor approximation of
the real hippocamus and is thus too low for precise volumetric analysis. To determine
whether PTSD produces a change in brain structure volume, multiple images must be
scanned at higher resolution, before and after PTSD onset.
July 10
11
Example 3: A Draft Paragraph Lacking Transition Elements
The internet is a computer network that connects users from all over the world. The
internet is also the largest network in the world. There are currently over 20 million users
on the internet according a recent survey by Nielson Research. The internet is sometimes
called a "network of networks" because it a superset of smaller networks such as America
Online or Usenet. It allows users to communicate via email, discussion groups or
hypertext. Other services include file transfer, remote login and indexing programs.
Originally, these computer utilities were used solely for scientific research. The system
architecture was open to promote collaboration and the system was distributed so that in
the event of nuclear war it would be usable. Now these utilities are being used to
exchange pornography and hate literature. The inventors of the internet never expected
the network to be a distribution channel for pornography.
The Rewrite
With over 20 million users, the internet is the largest computer network in the world. The
internet's vast size results from its status as a network of networks, connecting many
smaller networks such as America Online and Usenet. As an umbrella network, the
internet allows subnet users to communicate via email, discussion groups or hypertext.
Other services include file transfer, remote login and indexing programs. The network's
size and utility make it ever more attractive to more users.
The popularity of the internet has led to a new set of problems unenvisioned by its
inventors. Originally, the internet was used solely for scientific research and defense
projects. The architecture was designed to be open to promote collaboration, and the
system was distributed so that it could withstand nuclear war. This open, decentralized
system has promoted a new degree of free speech: any user can communicate anything to
any other user at any time. The unprecedented levels of freedom have resulted in
unprecedented levels of the abuse of free speech, such as the exchange of pornography
and hate literature.
July 10
12
Example 4: More Missing Transitions
The SuperSolder process is a printed circuit board solder application process. It is an
alternative to Selective Solder Strip application that should provide thicker solder on land
pads and has shown better solder joint reliability. Many assembly houses have already
implemented SuperSolder into their processes. The industry is tending toward
SuperSolder because it offers many benefits over Selective Solder Strip. Intel, however,
must test SuperSolder's reliability and manufacturability in its assembly line before
beginning production scale use of this potentially beneficial process.
The Rewrite
The SuperSolder printed circuit board solder application process is an alternative to
Selective Solder Strip. SuperSolder's advantages include: thicker solder on land pads, the
elimination of expensive photolithography steps, and better solder joint reliability.
Because the SuperSolder offers many benefits over Selective Solder Strip, the industry is
tending toward SuperSolder; many assembly houses have already implemented
SuperSolder into their processes. Before SuperSolder can be incorporated into Intel's
own production scale assembly line, the reliability and manufacturability of the new
process must be demonstrated inhouse.
July 10
13
Example 5: a Paragraph with Incorrect Transition Elements
The field of chemical process design has long been divided into two areas: process
simulation and chemical information. Recently, with the help of advanced computer
technology, process simulation has achieved significant commercial success. Several
simulation software packages, such as ASPEN, SPEEDUP, and ABACUS, have been
widely employed in the chemical industry, from unit operation to plant design. On the
other hand, the last fifteen years have witnessed major breakthroughs in the
acquisition of chemical information. Ab initio type quantum chemical calculations, armed
with ever more powerful computing facilities, have been provided reliable physical and
kinetic information for a wide range of chemicals. At the same time, chemical databases,
such as Chemical Abstract, have been able to provide rapid access to variety of chemical
information. However, there exists a big gap between the two areas mentioned above,
and a link needs to be built to enhance the cooperation between chemical information and
process simulation. The success of process simulation depends largely on the
accessibility and accuracy of physical and kinetic information for the chemicals involved.
Currently, there are two major ways to obtain chemical information: ab initio calculation
and chemical databases.
The Rewrite
The success of process simulation depends largely on the accessibility and accuracy of
physical and kinetic information for the chemicals involved. Recently, process simulation
has achieved significant commercial success with the help of advanced computer
technology. Several simulation software packages, such as ASPEN, SPEEDUP, and
ABACUS, are widely employed in tasks from unit operation to plant design. Simulation
improvements have been paralleled by major breakthroughs in the acquisition of
chemical information. Currently, there are two major ways to obtain chemical
information, ab initio calculation and chemical databases. Quantum, ab initio chemical
calculations now produce reliable physical and kinetic information for a wide range of
chemicals, and chemical databases, such as Chemical Abstract, provide rapid access to
variety of chemical information. While both process simulation and its information basis
have advanced, the linkage between them has not.
July 10
14
Exercise 1: Paragraph Coherence
Courtesy of Jim Paradis
Recommendation 5.6
The original design bases for a facility may have become lost due to the passage of time,
reorganization, lack of record keeping, or lack of training. When such records are lost,
any change of operation, addition of new processes, or any off-normal situation may
jeopardize the integrity of the facility if it is used in a manner for which it was not
designed. Many DP organizations and contractors therefore should consider
reestablishing the design bases for their facilities. They should also designate a standing
committee to review and approve all facility modifications.
July 10
15
Exercise 2: Paragraph Coherence
Courtesy of Jim Paradis
According to the chemiosmotic hypohesis of oxidative and photosynthetic
phosphorylation proposed by Mitchell (Refs 1-4), the linkage between elecron transport
and phosphorylation occurs not because of hypothetical energy-rich chemical
intermediaries as in the common view, but because the oxido-reduction and hydrolysis of
adenosine triphosphate (ATP) are each separately associated with the net translocation of
a certain number of electrons in one direction and the same number of hydrogen atoms in
the opposite direction across an ion-, acid-, and base-impermeable coupling membrane
(see also Ref 5).
July 10
16
Exercise 3: Paragraph Coherence
Courtesy of Jim Paradis
We have made these comments with specific reference to water. This is only because of
our familiarity with water. All pure substances exhibit the same general behavior. The
triple-point temperature and critical temperature vary greatly from one substance to
another. The critical temperature of helium is 9.5R. This is given in Table7. The
absolute temperature of helium at ambient conditions is over 50 times greater than the
critical temperature. Water has a critical temperature of 705.4F (1165R). At ambient
conditions, the temperature of water is less than half of its critical temperature.
July 10
17
Example: Broken at the Word & Punctuation Level
Metastasis is a complex multi-step process, where tumor cells are released and spread to
distant organs through the lymphatic system and invade blood vessels. There are tumor
cells which survive the journey through the blood and lymphatic system, and infiltrate
into preferred organs through extravasation of capillaries. Tumor metastasis is often
associated with altered cell-surface carbohydrate composition and an increase in average
molecular weight of asparagine-linked complex-type carbohydrates (F, 1991, and S,
1995). Carbohydrate moieties attached by glycosyltransferases serve as modulators and
regulators by which the cell interacts. They act mainly as the receptors on cell surfaces.
Changes in glycosyltransferase activity results in key alteration of oligosaccharids located
at the cell surface, leading to malfunction, that is lack of recognition and decreased cell
adhesion. Unfortunately, these conditions allow tumor cells to dissociate, which causes
metastasis and lowered response to the peripheral structures of other cells. This may lead
to persistent cell division and invasion of normal tissue: cancer.
July 23
18
6 Graphics Guidelines:
1. A picture is worth a thousand words; the higher the information density, the better. As
a corralary, a picture that is worth fewer than a thousand words should be removed
from a document.
2. As with text, structure will be vital if large amounts of information are to be
conveyed. Expository issues of purpose, context, beginning/middle/end, and design
apply to graphics. Often the graphic's structure is predetermined and well known by
both the reader and the author. When the structure is new, extra care must be taken to
convey order the reader.
3. Graphics must convey information visually; the reader must be able to “see”
something when looking at the figure. While the expository issues are similar, the
principles of graphic design can be very different, and the tools and methods used to
achieve visual impact are often quite different from those used to produce textual
impact. For an in depth coverage of graphic design principles relevant to technical
writing, I can recommend Edward Tufte's The Visual Display of Quantitative
Information and Envisioning Information.
4. The graphic must be referenced in the text. “See Figure 1” is not sufficient.
Additionally, the reader must be told what to “see” when looking at the graphic, and
how the figure relates to the text.
5. The use of graphics provides a second representation of the ideas found in the text.
Such multiple representation has two benefits. First, because readers preferentially
absorb information from some media, a variety of representations -- pictures, graphs,
tables, and text -- gives the reader a better chance of immediately grasping the
author's idea. Secondly, these multiple representations provide a more complete
picture of a complicated idea. If the reader can approach the same idea from different
vantages, the big picture is more easily grasped. The understanding of a complicated
idea is complete when the reader can comfortably switch between different the idea's
representations. (See the work of Judah Scwartz for more information on the
relationship between multiple representations and learning complex ideas.)
6. Like text, graphics are edited; they go through drafts, through write-read-think-editwrite cycles.
July 23
19
Graphics Exercise
Figure 7 needs help. The Y axes are not the same; one is volume adsorbed, the other
volume per gram of adsorbant. And Figure 7b is referenced before Figure 7a. The real
offence is the lack of visual impact and the clarity.
Propose a better display of this information. Do not hesitate to edit the paragraph as you
adjust the figure.
From Colloid Chemistry, H.B. Weiser, Wiley & Sons, 1939
July 23
20