Upload
amber-wilson
View
228
Download
0
Embed Size (px)
DESCRIPTION
Planning: Before You Begin Identify your audience and their expectations Know your purpose Know your material Understand the writing task at hand Organize your thoughts and materials Budget adequate time to write, review, revise and edit
Citation preview
Technical Writing 101
Abbreviated Version
Mr. Grimming
Good Technical Writers Practice
• Planning• Clarity• Simplicity• Word Choice• Active Voice• Committing to a Writing Process
Planning: Before You Begin
• Identify your audience and their expectations• Know your purpose Know your material• Understand the writing task at hand• Organize your thoughts and materials• Budget adequate time to write, review, revise and
edit
Clarity: Avoid Jargon• Jargon: a vocabulary particular to a place of work
(abbreviations, slang)• Audience familiarity with the topic determines
appropriate use of jargonEx. 1: For the first year, the links with SDPC and the HAC were not connected, and all required OCS input data were artificially loaded. Thus CATCH22 and MERWIN were not available.Ex. 2: Because some of the links in the computer system were not connected the first year, we could not run all the software codes.
Clarity: Define the Unfamiliar• If you must abbreviate, define the term in its first
occurrence, and put abbreviations in parenthesesEx: Edgartown Great Pond (EGP) is a vital body of water. Unfortunately, due to an unpredictable influx of saltwater, the delicate ecosystem is in danger of destabilizing.
• Italicize first occurrence of unfamiliar terms and define them right away
Ex: Retina is a light-sensitive tissue, found at the back of the eye, that converts light impulses to nerve impulses.
Brevity: Use Words Efficiently
• Never use two words when one word will do.Ex. 1: The relationship between the nature of salt water to fresh water in Indian River that fluctuates often is extremely important to everyone including scientists, residents, and environmentalists on Tampa Bay Area.Ex. 2: The fluctuating salinity of Indian River concerns many environmentalists, scientists, and residents.
Brevity: Less is More• Pare your language down to the essential message
you want to get across to your readers:Ex: Additional longitudinal modes can occur at predictable intervals as the laser cavity is increased. Depending on the length and gain within the cavity, the amount of modes can be easily calculated. For the HeNe laser, increasing the length past the confocal length will cause the number of modes to at least double. However, additional modes may not be as stable as those that occur in a shorter cavity.
Brevity: Most Important First
• Place key information in the main clause
Ex. 1: Besides making their fans very happy, the Buccaneers advanced to the playoffs with their shut out win over the Patriots.Ex. 2: The Buccaneers advanced to the playoffs after their shut-out win making their fans very happy.
Brevity: Avoid Redundancy
• Combine overlapping sentences when possible• Ex. 1: Water quality in Indian River declined in
March. This decline occurred because of the heavy rainfall that month. All the extra water overloaded the county’s water treatment plant.• Ex. 2: Water quality in Indian River declined in
March because heavy rainfalls overloaded the county water treatment plant.
Simplicity: Use Details Wisely• Specific details are desirable, but be careful to
balance detail with audience needs for clarity—significance is more important.
Ex. 1: The average Nd:YAG laser outputs 1064 nm.Ex. 2: The average Nd:YAG laser outputs 1064 nm when pumped using a 808 nm optical source. Its spectral linewidth is 0.5 nm when the crystal temperature is stabilized at room temperature.
Simplicity: Use Details Wisely• Many want to provide as much specific detail as
possible, but this can come at the expense of readers understanding and their main point
Ex. 1: The absorption cross section for the Yb:KGW or Ytterbium doped Potassium-Gadolinium Tungstate, (Yb:KGd(WO4)2) crystal is enormous. When doped to 5.0000%, the crystal has an absorption cross section of 1.2342343x10-19 cm2
Ex. 2: The absorption cross section for the Yb:KGW crystal is enormous. At 5% doping, the absorption cross section is 1.2x10-19 cm2
Language: Needless Complexity
Category Example SubstituteNouns utilization
functionalityusefeature
Verbs facilitatefinalize
causeend
Adjectives aforementionedIndividualized
mentionedIndividual
Adverbs firstly, secondly, heretofore
first, second, previous
Language: Needless Words
(already) existing never (before)at(the) present (time) none (at all)(basic) fundamentals now (at this time)(completely) eliminate period (of time)(continue to) remain (private) industrycurrently (being) (separate) entities(currently) underway start (out)(empty) space write (out)had done (previously) (still) persistsIntroduced (a new) mix (together)
Language: Ambiguity• Choose words whose meanings are clear.• Use parenthesis when needed.
Ex. 1: The lady hit the man with the umbrella.
Ex. 2:
Language: Ambiguity• Do not overuse pronouns—particularly “it”and
“this”—because it is often difficult to identify the antecedent
Ex: Because the receiver presented the radiometer with a high-flux environment, it was mounted in a silver-plated stainless steel container.
Language: Weak vs. Strong
• Avoid too many “to be” verbs• “is” “was” “were” “has been” “have been”• Avoid excess words, which slow comprehension of
the main pointMade arrangements for ArrangedMade the decision DecidedMade the measurement of MeasuredPerformed the development of DevelopedIs working as expected Works as expected
Active Voice: Strong Verbs
• Technical writers want to communicate as efficiently as possible, and active voice is more straight forward and is stronger than passive voice
Ex 1: The feed through was composed of a sapphire optical fiber, which was pressed against the pyrotechnic that was used to confine the charge.Ex 2: The feed through contained a sapphire optical fiber, which pressed against the pyrotechnic that contained the charge.
Active Voice: Natural Sound
• When in doubt, read passages out loud to determine the natural sound
Ex 1: A new process for eliminating nitrogen oxides from diesel exhaust engines is presented. Flow tube experiments to test this process are discussed. A chemical reaction scheme to account for this process is proposed.Ex 2: We present a new process for eliminating nitrogen oxides from the exhaust of diesel engines. To test this process, we performed experiments in flow tubes. To explain this process, we developed a scheme of chemical reactions.
Writing is a Process• Good writing doesn’t happen
overnight; it requires planning, drafting, rereading, revising, and editing.• Learning and improvement
requires self-review, peer-review, subject-matter expert feedback, and practice.• There are no shortcuts;
practice makes perfect!
Objective• Usually starts with “The purpose of this laboratory
exercise is” or similar phrase. • The purpose of this laboratory is to observe the digital
functions of a Schmitt Trigger.
• Next sentences should summarize the experiments to be conducted.• During this laboratory we will vary the external circuit
parameters, such as the time constant and clock speed, and observe the effects on the output.
The Material• List the equipment used with descriptions• HeNe Laser, Melles Gioret, Model PHP-30, 5 mW, 633 nm
• If it is a piece of test equipment use model and serial number. • Oscilliscope, B&H Model 2528, S/N: 4342
• Combine similar items.• Resistors (10 Ω, 100 Ω, 2 x 50 Ω)
• Use bullet format• Do not list standard lab equipment, wires, posts,
scews, etc.
Background• This includes theoretical information about your
circuit.• A Schmitt Trigger is a monostable vibrator that will
remain in its semi-stable state for a period equal to the time constant of an RC circuit. At the end of the time period it will return to the ground state. The time constant is calculated by:
T = RC (Eq. 1)
Procedures• This a “brief” guide about how the experiment was
conducted.• Do not give a recipe.• In part one of this lab a external circuit was connected to
the Schmitt trigger using the xxx resistor and xxx capacitor to establish a time constant of xxxx. The figure below shows the circuit diagram.
• Using a manual clock signal, we observed the changes in the indicator LED with each pulse.
Data and Observations• Show measured data and calculations results. • Make it neat! Use tables and graphs. Use proper
column and row labels etc.• Present your data with a statement:
• The following table shows the LED outputs of the first part of the exercise.
• We noticed that if we increase the frequency above 10 Hertz, the counter would skip a clock signal. This is most likely due to the clock periods being shorter than the time constant.
Answers• Include the question with the answer. • If calculations are required, show the calculations• Answer in complete sentences.
Conclusion• This is not where you complain about your
equipment, lab group, or instruction.• Summarize in a few statements responding to your
objective. • What did the experiment help you understand
about the equipment used.• Comment if you did any self exploration before
taking apart you circuit.