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
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.
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.
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.
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.
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, ( 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
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…
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.
1
July 9
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.
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...
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.
Example 3: A Draft Paragraph Lacking Transition Elements
The internet is a computer network thatconnects users from all over the world.The internet is also thelargest network in the world. There are currently over 20 millionusers on the internet according a recent survey by Nielson Research.The internet is sometimes called a "network of networks" because it asuperset 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.