keep it as simple as possible, yet no simpler. albert einstein how we will evaluate the writing of...
Post on 29-Dec-2015
216 Views
Preview:
TRANSCRIPT
Keep it as simple as possible, yet no simpler.
Albert Einstein
How We Will Evaluate the Writing of Engineering Documents
2
In engineering, the way that you write depends on the audience, purpose, and occasion
audience
purpose occasion
to inform
to persuade
format
formality
politics
deadlines
what do they know?why are they reading?
what expectations do they have?what biases do they have?
3
This lecture present ways to avoid common errors of structure in writing
StructureOrganization illogicalAssertions not supported Depth lackingSection transitions abrupt
LanguageAudience not targeted Improper toneAmbiguityNeedless complexitySentence variety lackingDiscontinuity
FormFormat not followedMajor error (RO, Frag)Grammar errorPunctuation errorUsage error
IllustrationIllustration not introducedIllustration misplacedIllustration not captioned
4
One error of structure is not properly organizing the document
EverestNews.com
IntroductionSummary Title
ReferencesAppendicesConclusion
If a man can organize his ideas, then he is a writer.
Robert Louis Stevenson
ResultsMethods
The organization of a document is reflected in the headings, subheadings, and paragraphs
6
Avoid abrupt beginnings to documents or sections
Heading
Experiment. The specimens were thin-walled tubes of 304L stainless steel...
Experiment. The experiment for the project consisted of several specimens placed inside a recirculating wind tunnel. The specimens were thin-walled tubes of 304L stainless steel...
Each citation at the end of the report should refer to a reference listing in the text
Introduction
[Spasov, 2002]
1
References
Armstrong, James, “Computer Engineering Laboratories Website at Penn State,” http://www.ee.vt.edu/cel (State College, PA: CSE Department, 2005).
Microchip Technology, “Specification Sheet DS11109G for the 28C64A” (Chandler, AZ: Microchip Technology, 1994), pp. 14-17.
Spasov, Peter, Microcontroller Technology: The 68HC11, 3rd ed. (Englewood Cliffs, NJ: Prentice Hall, 2002), p. 243.
26
8
This lecture present ways to avoid common errors of language in writing
StructureOrganization illogicalDepth lackingAssertions not supportedSection transitions abrupt
LanguageAudience not targeted Improper toneAmbiguityNeedless complexitySentence variety lackingDiscontinuity
FormFormat not followedMajor error (RO, Frag)Grammar errorPunctuation errorUsage error
IllustrationIllustration not introducedIllustration misplacedIllustration not captioned
To target the audience, write the procedures as a narrative, not a set of instructions
Procedures for Design
1. Load the contents of the A register into accumulator A and logically and it with $01.
2. If the result is equal to zero (meaning that the LSB of A was a zero), then branch to our inline ‘setlow’ routine, which clears accumulator A and puts it into the B register.
Procedures for Design
The second part of the laboratory called upon us first to read the level of a DIP switch and then to output that value to a TIL311 hex display. When the switch was open (state zero), the voltage was 5 V. Similarly, when the switch was closed, the voltage was 0....
10
In formal reports, the tone should be professional
…At this point, we realized that we had neglected at every step to test the program on its own. When we did test the program disconnected from a personal computer, the program went berserk. To our astonishment, when we reentered Buffalo, we discovered that our program no longer existed where we had stored it. Therefore, we have no way of knowing what the HC11 had been doing, but it certainly had been up to no good.
11
In formal reports, the tone should be professional
…At this point, we realized that we had neglected at every step to test the program on its own. When we did test the program disconnected from a personal computer, the program went berserk. To our astonishment, when we reentered Buffalo, we discovered that our program no longer existed where we had stored it. Therefore, we have no way of knowing what the HC11 had been doing, but it certainly had been up to no good.
Informal: you, a lot, pretty straightforward
12
An ambiguity is a group of words that can have more than one meaning
We examined neat methanol and ethanol and methanol and ethanol with 10% water.
We examined four fuels: neat methanol, neat ethanol, methanol with 10% water, and ethanol with 10% water.
13
Syntax often causes ambiguities,especially with adverbs
Only I tested the Labrador for rabies yesterday.
I only tested the Labrador for rabies yesterday.
I tested the only Labrador for rabies yesterday.
I tested the Labrador only for rabies yesterday.
I tested the Labrador for rabies only yesterday.
14
Word choice can also cause ambiguities
We wanted to reduce the vibration of the fan at the exhaust as the exhaust ducting was cracking.
We wanted to reduce the vibration of the fan at the exhaust because the exhaust ducting was cracking.
15
Not having commas after introductory phrases or clauses often causes ambiguities
After the display loop runs it returns to check the status of the switch.
After the display loop runs, it returns to check the status of the switch.
Also causing ambiguities are pronouns, particularly the pronouns it and this
Although engineers realized the design flaws in the Titanic soon after its sinking in 1912, the reasons for the severe damage inflicted by the iceberg remained a mystery until its discovery in 1985.
Although engineers realized the design flaws in the Titanic soon after its sinking in 1912, the reasons for the severe damage inflicted by the iceberg remained a mystery until the Titanic’s discovery in 1985.
17
Also causing ambiguities are pronouns, particularly the pronouns it and this
We wanted to load Port B with a 1 if the switch was high and with a 0 if the switch was low, which was easily done using a BRCLR statement with a mask of 1. This meant that if the low bit of Port A was clear, the code would output to Port B.
???????
One common error in engineering writing is to make the writing needlessly complex
Content:Ideas
Inherent complexity:Buffalo disassembler detailed schematicsEEPROM$006
Needless complexity:facilitation, e.g., PORT ALong noun stringsSentences containing more
than one idea
Style and Form:Writing
19
Complex wording buries ideas
R.I.P.
This study will consider why current solar energysystems, such as Solar One, have not reached thecommercial stage and will find out what steps we can take to make these systems commercial.
The goal of this study is to develop a commerciali-zation strategy for solar energy systems by analyzingfactors impeding early commercial projects (i.e., SOLAR ONE) and by identifying the potential actionsthat can facilitate the viability of the projects.
20
Needless complexity can occur at the sentence level
The goal of the work was to confirm the nature of electrical breakdown of nitrogen in uniform fields at high pressures and electrode gaps which approach those obtained in engineering practice, prior to the deter-mination of the processes which set the criterion for breakdown in the above-mentioned gas in uniform and non-uniform fields of engineering significance.
At high pressures (700 torr) and typical electrode gapdistances (1 mm), the electrical breakdown of nitrogen was studied inuniform fields.
21
The more challenging the idea, the more revisions are needed to clarify it
At high pressures (760 torr) and typical electrode gapdistances (1 mm), the electrical breakdown of nitrogen was studied inuniform fields.
In our study, we examined the electrical breakdown of nitrogen in uniform fields. For these experiments, the electrode gap distances were typical (1 mm), while the pressures were relatively high (760 torr).
22
Mount St. Helens erupted on May 18, 1980. A cloud of hot rock
and gas surged northward from its collapsing slope. The cloud
devastated more than 500 square kilometers of forests and
lakes. The effects of Mount St. Helens were well documented
with geophysical instruments. The origin of the eruption is not
well understood. Volcanic explosions are driven by a rapid
expansion of steam. Some scientists believe the steam comes
from groundwater heated by the magma. Other scientists
believe the steam comes from water originally dissolved in the
magma. We need to understand the source of steam in
volcanic eruptions. We need to determine how much water the
magma contains.
When sentence openers do not vary, the sentences do not seem to connect Z
Z
Z
23
Varying sentence openers allows for more kinds of transitions between sentences
Sentence 1 Sentence 2 Sentence 3
Topic of Sentence
Time or place of action
Manner of action
Subordinate action
Reason for action
Sentence
24
Vary sentence openers to vary rhythm
Mount St. Helens erupted on May…
subject–verb
In minutes, the mountain emitted…
prepositional phrase
However, debate has arisen... adverb
Although the exact time of the eruption surprised scientists, evidence had been collected...
dependent clause
25
More sophisticated sentence openers exist
gerundial phrase Calculating the amount of ash will require many assumptions.
dependent clause How the blast occurred remains as subject a mystery.
participial phrase Its slope collapsing, the mountain emitted...
infinitive phrase To understand the eruption, scientists have to...
Varying sentence openers enlivens the writing and allows connections
Mount St. Helens erupted on May 18, 1980. Its slope
collapsing, the mountain emitted a cloud of hot rock and gas.
In minutes, the cloud devastated more than 500 square
kilometers of forests and lakes. Although the effects of the
eruption were well documented, the origin is not well
understood. Volcanic explosions are driven by a rapid
expansion of steam. Recently, debate has arisen over the
source for the steam. Is it groundwater heated by magma or
water originally dissolved in the magma itself? To understand
the source of steam in volcanic eruptions, we need to
determine how much water the magma contains.
27
To make connections, use transitional phrases early in sentences
Also,
Moreover,
First…Second...
For that reason,
Therefore,
For instance,
For example,
Strictly speaking,
In other words,
In effect,
However,
On the other hand,
Conversely,
Nevertheless,
Otherwise,
Continuation Pause Reversal
This shows...This means...
28
Replace the standalone “this” with a noun phrase that specifies the subject
The finite element modeling technique does not take into account the flexibility of the truss. This results in a low stiffness, which causes the natural frequency to be imprecise.
WeakTransition
…truss. This disregard for flexibility results in a low stiffness causing the natural frequency to be imprecise.
SuccessfulTransition
…truss. Not accounting for the flexibility results in a low stiffness causing the natural frequency to be imprecise.
FluidTransition
29
This lecture present ways to avoid common errors of illustration in writing
StructureOrganization illogicalDepth lackingAssertions not supportedSection transitions abrupt
LanguageAudience not targeted Improper toneAmbiguityNeedless complexitySentence variety lackingDiscontinuity
FormFormat not followedMajor error (RO, Frag)Grammar errorPunctuation errorUsage error
IllustrationIllustration not introducedIllustration misplacedIllustration not captioned
30
Table 1. Physical characteristics of planets [Handbook, 1969].
Planet Diameter (km) Year (earth days)
Mercury 5,100 88
Venus 12,600 225
Earth 12,800 365
Mars 6,900 687
Jupiter 143,600 4,333
Saturn 120,600 10,759
Uranus 53,400 30,686
Neptune 49,500 60,225
Illustrations consist of tables and figures
*Pluto not considered here as a planet
*
31
0
0.5
1
1.5
2
2.5
3
0 500 1000 1500 2000 2500 3000 3500
Flow Rate of Air (cfm)
Stat
ic P
ress
ure
Ris
e (in
H2O
)
Load Curve Vanes 100% Open
Vanes 75% Open Vanes 65% Open
Vanes 50% Open Vanes 25% Open
Figure 1. Static pressure versus flow rate for five settings on the inlet guide vanes. The circles show where the fan would operate for each setting.
Illustrations consists of tables and figures
In formal documents, an illustration appears after the paragraph that introduces it
Figure 1. Simplified schematic of hardware.
..., as shown in Figure 1 below.
Port B
Port A
Hex Display(TIL311)
PB0-PB3
PA0-PA2 DIPSwitches
HC11
Figure 1. Simplified schematic of hardware.
..., as shown in Figure 1.
Port B
Port A
Hex Display(TIL311)
PB0-PB3
PA0-PA2 DIPSwitches
HC11
33
An equation is part of the sentence that introduces it
The goal of the project was to find the strain on the rim of an aluminum can. This strain, , was found from equation 1:
where is the stress estimated by the computer code, and E is the modulus of elasticity.
=
E(1),
34
This lecture present ways to avoid common errors of form in writing
StructureOrganization illogicalDepth lackingAssertions not supportedSection transitions abrupt
LanguageAudience not targeted Improper toneAmbiguityNeedless complexitySentence variety lackingDiscontinuity
FormFormat not followedMajor error (RO, Frag)Grammar errorPunctuation errorUsage error
IllustrationIllustration not introducedIllustration misplacedIllustration not captioned
A run-on (RO) is the incorrect joining of two sentences with a comma
Rubidium is more common in the earth than zinc, copper, or nickel, however, rubidium has no major uses.
Rubidium is more common in the earth than zinc, copper, or nickel. However, rubidium has no major uses.
Rubidium is more common in the earth than zinc, copper, or nickel; however, rubidium has no major uses.
Although rubidium is more common in the earth than zinc, copper, or nickel, rubidium has no major uses.
Correction:
36
To decide upon the verb tense in a document, you first plant a reference flag for t = 0
The pressure was...For the experiment, we
assumed…
Air is 79 percent nitrogen.Figure 1 shows…This section presents...
Past Tense:Events that have already occurred
Present Tense:Timeless details or details at time of reading
Future Tense:Events that will occur after project
Future work will focus on....
t = 0
t
37
In summary, the way you write depends on your audience, purpose, and occasion
audience
purpose occasion
to inform
to persuade
format
formality
politics
deadlines
what do they know?why are they reading?
what expectations do they have?what biases do they have?
top related