Docstoc

writing

Document Sample
writing Powered By Docstoc
					How We Will Evaluate the Writing
of Engineering Documents



Keep it as simple as
possible, yet no simpler.

       Albert Einstein
In engineering, the way that you write depends on
the audience, purpose, and occasion
 what do they know?                 what expectations do they have?
 why are they reading?              what biases do they have?
                         audience

                                            occasion
      purpose
                                            format
        to inform
                                            formality
     to persuade
                                            politics

                                            deadlines




                             2
This lecture present ways to avoid common errors
of structure in writing

 Structure                        Illustration
 Organization illogical           Illustration not introduced
 Assertions not supported         Illustration misplaced
 Depth lacking                    Illustration not captioned
 Section transitions abrupt


 Language                         Form
 Audience not targeted            Format not followed
 Improper tone                    Major error (RO, Frag)
 Ambiguity                        Grammar error
 Needless complexity              Punctuation error
 Sentence variety lacking         Usage error
 Discontinuity


                              3
One error of structure is not properly
organizing the document
                                  References
                                  Appendices
                                  Conclusion
If a man can organize his
ideas, then he is a writer.
Robert Louis Stevenson




                                               Results
                                               Methods


                                    Introduction
                                    Summary
EverestNews.com
                              4     Title
The organization of a document is reflected in
the headings, subheadings, and paragraphs
Avoid abrupt beginnings to documents
or sections

                  Experiment. The specimens were
                  thin-walled tubes of 304L stainless
 Heading          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...


                        6
Each citation at the end of the report should
refer to a reference listing in the text

                                References

                                Armstrong, James, “Computer Engineering
                                   Laboratories Website at Penn State,”
                                   http://www.ee.vt.edu/cel (State College, PA: CSE
                                   Department, 2005).
Introduction
                                Microchip Technology, “Specification Sheet
                                   DS11109G for the 28C64A” (Chandler, AZ:
                                   Microchip Technology, 1994), pp. 14-17.

                                Spasov, Peter, Microcontroller Technology: The
               [Spasov, 2002]      68HC11, 3rd ed. (Englewood Cliffs, NJ: Prentice
                                   Hall, 2002), p. 243.




                                                            26




                  1
This lecture present ways to avoid common errors
of language in writing

 Structure                        Illustration
 Organization illogical           Illustration not introduced
 Depth lacking                    Illustration misplaced
 Assertions not supported         Illustration not captioned
 Section transitions abrupt


 Language                         Form
 Audience not targeted            Format not followed
 Improper tone                    Major error (RO, Frag)
 Ambiguity                        Grammar error
 Needless complexity              Punctuation error
 Sentence variety lacking         Usage error
 Discontinuity


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




                             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.


        Informal: you, a lot, pretty straightforward

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


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



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


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


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




             ???????

                              17
One common error in engineering writing is
to make the writing needlessly complex

                               Inherent complexity:
 Content:                      Buffalo disassembler
 Ideas       Style and Form:   detailed schematics
                               EEPROM
             Writing           $006

                               Needless complexity:
                               facilitation, e.g., PORT A
                               Long noun strings
                               Sentences containing more
                                 than one idea
Complex wording buries ideas


This study will consider why current solar energy
systems, such as Solar One, have not reached the
commercial stage and will find out what steps
we can take to make these systems commercial.



                                                    R.I.P.

The goal of this study is to develop a commerciali-
zation strategy for solar energy systems by analyzing
factors impeding early commercial projects (i.e.,
SOLAR ONE) and by identifying the potential actions
that can facilitate the viability of the projects.
                             19
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             At high pressures (700 torr)
 electrode gaps which approach            and typical electrode gap
 those obtained in engineering            distances (1 mm), the
 practice, prior to the deter-            electrical breakdown of
 mination of the processes which          nitrogen was studied in
 set the criterion for breakdown          uniform fields.
 in the above-mentioned gas in
 uniform and non-uniform fields of
 engineering significance.




                                     20
The more challenging the idea, the more
revisions are needed to clarify it



                                    In our study, we examined
                                    the electrical breakdown of
At high pressures (760 torr)        nitrogen in uniform fields.
and typical electrode gap           For these experiments, the
distances (1 mm), the
electrical breakdown of             electrode gap distances
nitrogen was studied in             were typical (1 mm), while
uniform fields.                     the pressures were
                                    relatively high (760 torr).




                               21
When sentence openers do not vary, the
sentences do not seem to connect                                          Z
                                                                      Z
                                                                  Z
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.


                                   22
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

    Sentence        Manner of action

                    Subordinate action

                    Reason for action

                        23
Vary sentence openers to vary rhythm

subject–verb           Mount St. Helens erupted
                       on May…


prepositional phrase   In minutes, the mountain
                       emitted…


adverb                 However, debate has arisen...


dependent clause       Although the exact time of the
                       eruption surprised scientists,
                       evidence had been collected...
                           24
More sophisticated sentence openers exist


infinitive phrase    To understand the eruption,
                     scientists have to...


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



                          25
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.
To make connections, use transitional phrases
early in sentences

Continuation       Pause                Reversal

Also,              For instance,        However,
Moreover,          For example,         On the other hand,
First…Second...    Strictly speaking,   Conversely,
For that reason,   In other words,      Nevertheless,
Therefore,         In effect,           Otherwise,


                   This shows...
                   This means...
                                27
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
                                                 Weak
truss. This results in a low stiffness, which    Transition
causes the natural frequency to be imprecise.

…truss. This disregard for flexibility results   Successful
                                                 Transition
in a low stiffness causing the natural
frequency to be imprecise.


…truss. Not accounting for the flexibility       Fluid
results in a low stiffness causing the natural   Transition

frequency to be imprecise.
                               28
This lecture present ways to avoid common errors
of illustration in writing

 Structure                         Illustration
 Organization illogical            Illustration not introduced
 Depth lacking                     Illustration misplaced
 Assertions not supported          Illustration not captioned
 Section transitions abrupt


 Language                          Form
 Audience not targeted             Format not followed
 Improper tone                     Major error (RO, Frag)
 Ambiguity                         Grammar error
 Needless complexity               Punctuation error
 Sentence variety lacking          Usage error
 Discontinuity


                              29
Illustrations consist of tables and figures

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
*Pluto not considered here as a planet




                                              30
Illustrations consists of tables and figures

                                 3
                                                       Load Curve                  Vanes 100% Open

                                                       Vanes 75% Open              Vanes 65% Open

                                2.5                    Vanes 50% Open              Vanes 25% Open
 Static Pressure Rise (inH2O)




                                 2




                                1.5




                                 1




                                0.5




                                 0
                                      0   500   1000                1500              2000           2500        3000   3500

                                                                    Flow Rate of Air (cfm)



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.



                                                                                                            31
In formal documents, an illustration appears
after the paragraph that introduces it


                                                ..., as shown in Figure 1.
  ..., as shown in Figure 1 below.

            PB0-PB3
   Port B                   Hex Display
                            (TIL311)                      PB0-PB3
                                                 Port B                   Hex Display
  HC11                                                                    (TIL311)

                                                HC11
            PA0-PA2      DIP
   Port A                Switches
                                                          PA0-PA2      DIP
                                                 Port A                Switches
  Figure 1. Simplified schematic of hardware.

                                                Figure 1. Simplified schematic of hardware.
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:
                         
                 =           ,              (1)
                        E
where  is the stress estimated by the computer
code, and E is the modulus of elasticity.




                              33
This lecture present ways to avoid common errors
of form in writing

 Structure                         Illustration
 Organization illogical            Illustration not introduced
 Depth lacking                     Illustration misplaced
 Assertions not supported          Illustration not captioned
 Section transitions abrupt


 Language                          Form
 Audience not targeted             Format not followed
 Improper tone                     Major error (RO, Frag)
 Ambiguity                         Grammar error
 Needless complexity               Punctuation error
 Sentence variety lacking          Usage error
 Discontinuity


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


Correction:

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.
To decide upon the verb tense in a document, you
first plant a reference flag for t = 0

 Past Tense:              Present Tense:               Future Tense:
 Events that have         Timeless details or          Events that will occur
 already occurred         details at time of reading   after project




                                   t=0
                                                                            t
The pressure was...      Air is 79 percent nitrogen.    Future work will
For the experiment, we   Figure 1 shows…                    focus on....
    assumed…             This section presents...


                                     36
In summary, the way you write depends on
your audience, purpose, and occasion
  what do they know?                 what expectations do they have?
  why are they reading?              what biases do they have?
                          audience

                                            occasion
      purpose
                                            format
        to inform
                                            formality
     to persuade
                                            politics

                                            deadlines




                             37

				
DOCUMENT INFO