Technical Writing Notes



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.

[pic]

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:

[pic] [pic]

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.

[pic]

Don’t write like an undergraduate.

[pic] [pic]

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.

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 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.

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.

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.

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.

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).

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.

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.

6 Graphics Guidelines:

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.

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.

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.

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.

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.)

Like text, graphics are edited; they go through drafts, through write-read-think-edit-write cycles.

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.

[pic]

From Colloid Chemistry, H.B. Weiser, Wiley & Sons, 1939

................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download