Guidelines for Technical Writing

Transcription

1 Guidelines for Technical Writing Kevin Shinpaugh AOE 4065 Material adapted from: The Craft of Scientific Writing, 3rd edition, Michael Alley, Springer- Verlag, New York, 1996.

2 When you are out to describe the truth, leave elegance at the tailor Everything should be as simple as it can be, yet no simpler. --- Albert Einstein

3 Constraints for Writing Audience Format Mechanics: rules of grammar and punctuation Politics Variables: Area of Science and Engineering for the Work Your purpose: inform, persuade, or both

4 Six Goals of Scientific Writing Precise Clear Familiar Forthright Concise Fluid

5 Being Precise The difference between the right word and the almost right word is the difference between lightning and lightning bug -- Mark Twain Choosing the right word Choosing the appropriate level of detail

6 Being Precise Words with incorrect meaning: affect/effect, comprise/compose Water is comprised/composed of hydrogen and oxygen. Phrase with no meaning: centers around instead of centers on or revolves around Avoid the temptation to use Synonyms Avoid absolutes: always and never Word with inappropriate connotation: The turbulence in the flow enhances/exacerbates/increases the drag by more than 20 percent.

7 Being Clear Avoid needles complexity: words, phrases, and sentences Solar one is a 10 megawatt solar thermal electric central receiver power pilot power plant. Avoid ambiguity: use of a word, phrase, or sentence that can be interpreted in more than one way The solar collector worked well under passing clouds.

8 Being Forthright Writing should be sincere and straightforward Tone: your attitude towards your subject Avoid pretentious words, arrogant phrases, and clichés: Facilitate/implement/utilize/utilization as is well know / clearly demonstrate / it is obvious come up to speed / touch base Use strong nouns (concrete nouns - provides one of the five senses to the reader) and verbs (provides momentum in sentences) Avoid passive voice - slows your writing; reduces your writing efficiency

9 Being Familiar Avoid jargon ABC: American, British, and Canadian or atomic, biological, and chemical Define unfamiliar terms and abbreviations Bremsstrahlung is the electromagnetic radiation emitted (as photons) when a fast-moving charged particle (usually an electron) loses energy upon being accelerated and deflected by the electric field surrounding a positively charged atomic nucleus. Incorporate example and analogies

10 Being Concise Eliminate redundancies The aluminum metal cathode became pitted during the glow discharge already existing / at the present time / completely eliminate Eliminate dead wood it is interesting to note / as a matter of fact / it should be pointed out Reduce sentences to simplest forms Fat phrases: at this point in time - now Too many adjectives

11 Being Fluid Vary sentence rhythms Vary sentence openers Subject-verb Prepositional Phrase Transition Words Introductory clause Infinitive phrase Participial phrase Verb (question)

12 Being Fluid Vary sentence rhythms Vary sentence lengths Average length in the teens Change sentence length often, at least every two or three sentences Occasionally use a short or long sentence Vary sentence structure Three types: simple, compound, and complex Vary paragraph lengths Measured by the number of lines not sentences

13 Common Pitfalls of Grammar Do not join two independent clauses with an adverb. Present list items in a parallel fashion Have modifiers point to the words they modify Have each subject agree in number with the verb In each section of the document, maintain the same reference frame for the tenses of verbs

14 Summaries Please be good enough to put your conclusions and recommendations on one sheet at the very beginning of your report, so that I can even consider reading it -- Winston Churchill Descriptive: what kind of information will occur in the document Informative: what results occurred in the work

15 Introductions What exactly is the work? Why is the work important? What is needed to understand the work? How will the work be presented?

16 Tables and Figures Tables useful to present numerical data Higher accuracy than a graph Easy for reader to locate a reference number Figures include graphs, photographs, drawings, and diagrams When including these elements please discuss the significance in the text of the document. What do you want the reader to see or understand?

17 Title and Headings Be descriptive Parallelism Noun Phrase: Design phase Build Phase Operations phase Participial Phrase: Designing the spacecraft Building the spacecraft Operating the spacecraft

18 Captions Tables and Figures should be identified with a caption (heading) A caption should answer immediate question that the table or figure raises Caption should have a title phrase that identifies the table/figure and provide enough information to separate it from other tables/figures The caption should have additional sentences that clarifies and provides additional details Reasons: Readers eyes naturally are attracted to tables/figures A table/figure with its caption should be understood independently of the document