Technical writing (1)
1 like294 views
This document provides guidelines for writing effective engineering reports. It discusses the key components of an engineering report, including the title, abstract, introduction, theory and analysis, experimental procedures, results and discussion, conclusions, acknowledgments, references, and appendix. It recommends organizing the report with these main sections and using headings to break up the content. The document also provides tips for report style, mechanics, graphs, and conclusions.
Technical writing (1)
- 1. ENGINEERING REPORT WRITING Electrical and Computer Engineering Department University of Connecticut Storrs, CT 06269-2157 September 2003 Edition 1
- 2. INTRODUCTION. As a practicing engineer, you will need to write reports, proposals, scientific papers, and electronic messages. Writing is perhaps the most important way in which you will convey your ideas to managers, other engineers, and customers. Your communication skills will therefore determine how successful you are as an engineer, perhaps even more so than your technical expertise! This booklet describes briefly how to write an effective engineering report. As you read this booklet, keep in mind that there is always more than one way to convey the same idea. In many situations, there is not necessarily a “right way” and a “wrong way.” REPORT ORGANIZATION. Good report organization should promote readability and reflect the scientific method of attack, which proceeds with objective, method, results, and conclusions. It is logical to report a project in the sequence in which it is done, and many engineering reports are organized on this basis. Two improvements to the logical sequence are the addition of an abstract or executive summary and the insertion of headlines. These two features facilitate “scanning” of the report. Thus, a busy executive or engineer may quickly assess the major findings and conclusions of the report, and then easily find further details as required. In writing a full-length engineering report, you should start with a report outline, then proceed to a rough draft. The outline defines the organization of the report, and the rough draft serves to avoid omissions. Once the content is established, the rough draft is refined for clarity and conciseness. After proofreading and correction of minor mistakes, the finished product is produced. This entire writing process is most easily done using a word processor. “Spell checkers” are particularly useful in removing spelling or typographical mistakes. The outline for a general full-length engineering report contains the following items: 1. Title 2. Summary orAbstract (Executive Summary) 3. Introduction 4. Theory and Analysis 2
- 3. 5. Experimental Procedures 6. Results and Discussion 7. Conclusions and Recommendations 8. Acknowledgments 9. Literature Cited 10. Appendix The individual sections of the report will have headings, which are made to stand out with underlined, bold, italic, or large size print. The names of the sections may be more descriptive than the generic names listed above. Headings may be numbered, especially in longer reports, theses or books. Longer documents may also have subheadings within sections. A title page should be used with full identification including names and dates. If the report is long, a table of contents should follow the title page. The abstract should summarize the major points in the report in concise manner and should allow the reader to make a decision on whether or not to read the full paper. The first sentence should state what was accomplished. The abstract is not a condensation of the entire paper, but rather a clear statement of the project scope, results achieved, and the conclusions and recommendations drawn from the results. An introduction is desirable to indicate the background of the project and the reasons for undertaking it. Some information on previous work is usually included. In the theory and analysis section, pertinent principles, laws, and equations should be stated and unfamiliar terms should be defined. Analytical diagrams such as theoretical cycles or flow and field patterns should be shown here. Be sure to include all necessary supporting theory without adding deadwood. The experimental procedures section should describe apparatus and materials. Instrument types, ranges, and identification numbers should be indicated. A sketch of the test setup showing relative positions, connections, and flows should be included. Preliminary results, equalizing periods, duration of runs, and frequency of readings should be indicated. Special precautions for obtaining accuracy and for controlling conditions should be described. Conformity with or divergence from standard test codes or procedures should be clearly stated. 3
- 4. The results and discussion section should summarize the important findings with supporting tables, graphs, and figures. Original data or extensive data tables should be included in appendices. Graphical representation is very important in conveying quantitative results. The use of logarithmic or other special scales should be considered. Deviations from smooth curves should be carefully checked. Apparent discrepancies should be pointed out and explained. The discussion should describe the accuracy and importance of the results. Sources of measurement error should be evaluated. Results should be critically compared with theory, and differences greater than the experimental errors should be explained. Limitations of the theory and tolerances in engineering values should be considered. Conclusions should be supported by specific references to data and results, quoting numerical values, and guiding the reader from facts to conclusions. Conclusions should follow directly from the numerical results quoted, without the need for mental arithmetic by the reader. Omit any part of the discussion which could be written without performing the experiment. The conclusions and recommendations section should summarize the conclusions which have been drawn. These conclusions may be supported by brief reference to data or results. Recommendations are often more important than conclusions. Few experimental projects are an end in themselves. Either the results are to be used for a purpose, or the experimenter sees more work that could be done. In student reports, recommendations on improving the laboratory experiments, equipment or procedures are accepted gratefully. Acknowledgments are usually unnecessary in a student report. They are very important in theses, journal articles, or company reports. Always acknowledge all other contributors to the work, people who have contributed ideas or materials, and sources of financial support. The bibliography must list sources to which direct reference was made in the text. Other general references may also be given. Numbered footnotes, or preferably endnotes, are used to list sources in the order of reference. REPORT STYLE. 4
- 5. For many years, it was customary to write scientific papers in the third person, passive voice, past tense. Even today, this style is preferred by many. More and more, however, the first person, active voice, past tense is becoming the preferred style. Consider some examples: Not Recommended: Clean the gallium arsenide substrates by boiling them in trichloroethylene. Not Recommended: I clean the gallium arsenide substrates by boiling them in trichloroethylene. Acceptable: The gallium arsenide substrates were cleaned by boiling in trichloroethylene. Recommended: We cleaned the gallium arsenide substrates by boiling them in trichloroethylene. Simple technical English should be used. Engineering and trade terms may be used, but the style should be dignified. Short sentences are preferred. Acronyms may be used but only if they are defined at the first appearance. For further guidelines on style, see Appendix A, or refer to a writing handbook such as The Little, Brown Handbook, by H. R. Fowler (Boston: Little, Brown and Company, 1980), The Elements of Style, by William Strunk and E. B. White (New York: Macmillian, 1979), or Style: Ten Lessons in Clarity and Grace, by Joseph Williams (Glenview, IL: Scott, Foresman, 1981). REPORT MECHANICS. As a matter of general mechanics, you should use the following: uniform page size (8.5” x 11”); prominent headings; well- displayed tabulations with titles; well-displayed figures with titles; ample margins; and numbered pages. Reports submitted in University of Connecticut writing courses such as ECE 209W or ECE 262W must have letter-quality print produced by a laser printer or ink jet printer. Numerical results should be reported with due regard for the experimental accuracy with which they were obtained. For instance, 0.75 + 0.01 Ampere is acceptable but 5.3275 + 0.01 Volt is not. In the absence of explicitly stated errors, the error is assumed to be plus or minus one in the least significant digit. Hence 5.33 V means the same as 5.33 + 0.01 V. 5
- 6. Graphs should be numbered and completely labeled and titled. The title should be brief and descriptive, such as “Motor Speed as a function of Torque.” The independent variable should be shown on the abscissa (horizontal axis) and the dependent variable should be shown on the ordinate (vertical axis). Scales should be labeled with the name, symbol, and units of the quantity involved. Each of the curves on a sheet should be clearly identified, and all of the experimental points shown. Graph scales should be chosen for easy reading but with due regard to the accuracy of observed and computed quantities, so that variations are neither concealed nor exaggerated. For instance, if temperatures can be read only to the nearest degree, the smallest subdivision on the graph paper should be one degree or greater. Major scale divisions should be chosen so that interpolation is easy. The subdivisions should preferably represent 2, 5, 10, 20, 50, 100 etc. Most scales should start from zero; if they do not, a broken axis must be used. Smooth curves should be drawn with no extrapolation beyond the experimental points. Any discontinuities or points of inflection should be examined with suspicion. Methods of plotting that give straight lines are preferred. CONCLUDING REMARKS. Use this booklet as a guide, but remember that it can not take the place of good judgment. Every report is different. The unique content of a report may dictate the style or organization of the report. REFERENCES. H. R. Fowler, The Little, Brown Handbook (Boston: Little, Brown and Company, 1980). William Strunk and E. B. White, The Elements of Style (New York: Macmillian, 1979). G. L. Tuve and L. C. Domholdt, Engineering Experimentation (New York: McGraw-Hill Book Co., 1966). Craig Waddell, Basic Prose Style and Mechanics (Troy, NY: Rensselaer Press, 1990). 6
- 7. Joseph Williams, Style: Ten Lessons in Clarity and Grace (Glenview, IL: Scott, Foresman, 1981). 7
- 8. APPENDIX A: BASIC PROSE STYLE. 1. Write in the Active Voice. Always choose the active, rather than the passive voice, unless you have a good reason to do otherwise. With the active voice, the subject is the same as the agent (the person or thing carrying out the action). NO: A Fluke 77 digital multimeter was used by us. NO: A Fluke 77 digital multimeter was used. YES: We used a Fluke 77 digital multimeter. Notice that the verb to be usually flags the passive voice. 2. Avoid Nominalizations. Avoid nominalizations unless you have a good reason to do otherwise. A nominalization is a noun derived from a verb or adjective. NO: Our expectation was that the motor would run at 2400 rpm. YES: We expected that the motor would run at 2400 rpm. A noun string can act as a nominalization: NO: Computer center laser printer maintenance is performed monthly. YES: The laser printers in the computer center are maintained monthly. 3. Express Parallel Ideas in Parallel Grammatical Form. Units of equal function should be expressed in equal form. Repetition of the same structure allows the reader to recognize parallel ideas more readily: 8
- 9. NO: This type of speed control can be used with synchronous motors or motors of the induction type. YES: This type of speed control can be used with synchronous or induction motors. 4. Place the emphatic words at the end of the sentence. Joseph Williams offers two rules: 1. Whenever possible, express at the beginning of a sentence ideas already stated, referred to, implied, safely assumed, familiar - whatever might be called old, repeated, relatively predictable, less important, readily accessible information. 2. Express at the end of a sentence the least predictable, the newest, the most significant and striking information. NO: One billion bits is the capacity of the newest memory chips. YES: The newest memory chips hold one billion bits. Following this rule not only creates proper emphasis within the sentence, but also creates cohesion between sentences. 5. Express statements in positive form. The positive form is usually more concise. As Joseph Williams points out, To understand the negative, we have to translate it into an affirmative, because the negative only implies what we should do by telling us what we shouldn’t do. NO: Don’t write in the negative. YES: Write in the affirmative. 9
- 10. NO: Measurements of electrical current are not possible without first moving the red probe to the “mA” socket. YES: To make measurements of electrical current, first move the red probe to the “mA” socket. 6. Vary sentence patterns. Craig Waddell writes A series of sentences that follow the same general pattern (e.g., a series of three or four simple sentences or a series of three or four compound sentences) can be tedious. Avoid monotony by varying sentence patterns. One of the best ways to avoid a tedious series of simple sentences is to use subordination (or embedding) to combine the information presented in these sentences into a single, complex sentence. Compound and complex sentences can themselves, however, become tedious. And sometimes, they’re just plain awkward or confusing. Don’t overload your sentences or your readers. 7. Choose your words carefully. Some factors you should consider in choosing words are their connotation, tone, and level of formality. a. Connotation. While the dictionary meaning of a word is its denotation, the suggestive implication of a word is its connotation. For example, although pretty means “having conventionally accepted elements of beauty,” the connotation is generally feminine. Most men would prefer to be called “handsome.” b. Tone. The tone of a word expresses something about your attitude toward the person or thing being described. c. Level of Formality. Most dictionaries will describe words as formal, informal, vulgar, or obscene. However, your own judgment may be sufficient to guide you in making the appropriate choice for a given context. In engineering reports, slang, vulgar, or obscene 10
- 11. words or phrases are usually inappropriate and the style should be dignified. Be aware, however, that it is a mistake to be too formal at the expense of conciseness. As Joseph Williams writes, When we pick the ordinary word over the one that sounds more impressive, we rarely lose anything important, and we gain the simplicity and directness that most effective writing demands. 8. Avoid modifiers. Avoid overusing adjectives and adverbs. Instead, select words that don’t require adjectives or adverbs to supplement their meaning. 9. Clarify the logical relationships between your ideas. In order to make your writing clear and the transitions between ideas smooth, clearly express the logical relationships between ideas. Here are some suggested words for expressing the eight logical relationships. a. Addition: moreover, further, furthermore, besides, and, and then, likewise, also, nor, too, again, in addition, equally important, next, first, second, third, in the first place, in the second place, finally, last b. Comparison: similarly, likewise, in like manner c. Contrast: but, yet, and yet, however, still, nevertheless, on the other hand, on the contrary, even so, notwithstanding, for all that, in contrast to this, at the same time, although this may be true, otherwise d. Place: here, beyond, nearby, opposite to, adjacent to, on the opposite side e. Purpose: to this end, for this purpose, with this object f. Result: hence, therefore, accordingly, consequently, thus, thereupon, as a result, then g. Summary, repetition, exemplification, intensification: to sum up, in brief, on the whole, in sum, in short, as I have said, in other words, that is, to be sure, as has been noted, for example, for instance, in fact, indeed, to tell the truth, in any event h. Time: meanwhile, at length, soon, after a few days, in the meantime, afterward, later, now, in the past 10. Prune deadwood. 11
- 12. Deadwood is material that adds no meaning to the sentence or paragraph. Eliminate all deadwood to make your writing more concise. 11. Avoid redundancy. Redundancy is the unnecessary repetition of information. 12. Use metaphor to illustrate. Metaphor is imaginative comparison, expressed or implied, between two generally unlike things. Metaphors, though infrequently used in engineering reports, can illustrate abstract ideas: When two atoms approach each other at great speeds they go through one another, while at moderate speeds they bound off each other like two billiard balls.” Sir William Bragg However, you should avoid cliches. 12
- 13. APPENDIX B: BASIC PUNCTUATION AND MECHANICS 1. Commas 1.1.A Use a comma before a coordinating conjunction (and, but, or, for, yet, nor, so) that joins two independent clauses. The power supply was not damaged, but all of the integrated circuits burned up. 1.1.B A comma is not required if the clauses are short and closely related: Jose typed and Philip watched. 1.1.C If the coordiante clauses are long or contain commas themselves, semicolons may be used to separate them in order to avoid confusion. The teaching assistant provided the students with circuit diagrams, and checked their wiring; but several components were damaged when they applied power. 1.2 Use a comma to separate an introductory element (clause, phrase, conjunctive adverb, or mild interjection) from the rest of the sentence. If you ground two points in the circuit, a fuse may blow. (clause) Nevertheless, the doping behavior of gallium nitride is still not fully understood. (conjunctive adverb) 1.3 Use commas to set off parenthetical elements or interrupters (including transitional adverbs): The motor, which had been used for several years, suddenly failed. 13
- 14. 1.4 Use commas to join items in a series. Except in journalism, this includes a comma before the conjunction that links the last item to the rest of the series: Measurements were made using a Fluke digital multimeter, an analog wattmeter, and a Hewlett Packard oscilloscope. 1.5 Sometimes commas are required to avoid the confusion of mistaken junction: She recognized the man who entered the room, and gasped. 2. Semicolons 2.1 Use a semicolon to join two independent clauses that are closely related in meaning and are not joined by a coordinating conjunction. 2.2 Use a semicolon to join two independent clauses when the second one begins with or includes a conjunctive adverb (nevertheless, therefore, however, otherwise, as a result). 2.3 To avoid confusion, use semicolons to separate items in a series when one or more of the items includes commas. 3. Colons 3.1 Use a colon to introduce a list, an example, an amplification, or an explanation directly related to something just mentioned. 3.2 Use a colon to introduce a formal statement or quotation. 4. Dashes In typing, make a dash with two hyphens, leaving no space between them. Common word processors will convert two hyphens into a thin, continuous line. Dashes are somewhat informal—use them sparingly. 4.1 Use a dash to introduce a summarizing word, phrase, or clause, such as an appositive ( a noun set beside another noun and identifying it): 14
- 15. Richard Stone’s book describes overhead cams, double overhead cams, and overhead valves—all the important valvetrain configurations. 4.2 Use dashes to mark off a parenthetical element that represents an abrupt break in thought. Reagan’s sweep of the south—he won every state but Georgia—was the most humiliating defeat for Carter. 4.3 To avoid confusion, use dashes to mark off parenthetical elements that contain internal commas: Seven of our first twelve presidents—Washington, Jefferson, Madison, Monroe, Harrison, Tyler, and Taylor—were from Virginia. 5. Parentheses 5.1.A Use parentheses to enclose parenthetical elements. 5.1.B A parennthesized sentence that appears within another sentence need not begin with a capital or end with a period. 5.1.C A comma may follow the closing parenthesis, but one should not preceed the opening parenthesis. 6. Ellipsis Dots 6.1 Use three spaced dots to signal omission of a word or words in the middel of a quoted sentence or to signal hesitation or halting speech in dialogue. 6.2 Use four spaced dots to signal the omission of the end of a quoted sentence, or to signal the omission of one or more whole sentences. 7. Hyphens 15
- 16. 7.1 Use a hyphen to form a compound noun or a compound modifier: Rebecca Lobo was a scholar-athlete. 7.2 Use a hyphen between the components of any number (including fractions) below one hundred that is written as two words: one-half forty-three two-thirds 8. Apostrophes 8.1 Use apostrophe, s to indicate singular possessive: Most of the machines use Intel’s Pentium chip. 8.2 Use s, apostrophe to indicate plural possessive: The students’ lounge contains eight IBM workstations and a laser printer. 8.3 Use apostrophe, s to form the plural of abbreviations with periods, lowercase letters used as nouns, and capital letters that would be confusing without the apostrophe: M.S.’s and Ph.D.’s S’s and T’s x’s or y’s 8.4 When it can be done without confusion, use s alone to form the plural of letters, figures, and words treated as words: three Rs they come in twos the 1990s 9. Italics Underlining may be used as a substitute for italics. 9.1 Use italics to emphasize a word or phrase. 9.2 Use italics to identify a letter treated as a letter or a word treated as a word. 16
- 17. He used the word microchip fifty-four times in his speech. 9.3 Use italics to identify foreign words or phrases not yet absorbed into English. 10. Titles 10.1 Italicize or underline the titles of books, magazines, journals, newspapers, films, radio shows, and television shows. 10.2 Enclose in quotation marks the titles of journal articles, newspaper columns, songs, short stories, and book chapters. 11. Numbers 11.1 Spell out a number when it begins a sentence. 11.2 Spell out a number that can be written in one or two words. Twenty-three six four billion 11.3 If numbers that can be written as one or two words cluster closely together in the sentence, use numerals instead: We took measurements at 2, 5, 10, 12, and 15 GHz. 11.4 Use numerals if spelling out a number would require more than two words: 301 7,012 7.38 2.1 x 10-4 11.5 Use numerals for addresses, dates, exact times, exact sums of money, exact measurements, game scores, mathematical ratios, and page numbers: p. 6 75 mph a 2:1 ratio 12:50 am 12. Quotation Marks 17
- 18. 12.1 Use double quotation marks to create irony by setting off words you do not take at face value. His “lecture” pertained mostly to his visit to the Hawaiian volcanoes. 12.2 Do not use quotation marks to create emphasis. 12.3 Use single quotation marks to enclose a quotation within a quotation. 12.4 If the quotation will take more than three or four lines on the page, use indentation instead of quotation marks. 12.5 Do not use quotation marks with indirect discourse, or with rhetorical, unspoken, or imaginary questions: The professor said we could submit the homework on Friday. Why am I studying business administration? she wondered. 13. Punctuating Quotations 13.1 Do not use a comma to mark the end of a quoted sentence that is followed by an identifying tag if the quoted sentence ends in a question mark or an exclamation point: “Hit the kill switch!” he screamed. 13.2 Commas and periods go inside closing quotation marks; semicolons and colons go outside the closing quotation marks. 14. Introducing Indented Quotations, Lists, and Formulas The punctuation immediately following the introduction to an indented quotation, list, or formula is determined by the grammatical structure. 14.1 If the introduction is a main clause, follow it with a colon: Each student was asked to buy the following: 18
- 19. a protoboard a digital multimeter a laboratory manual a component kit 14.2 If the introductory element is not a main clause, follow it with a comma if one is required by 1.2: In VLSI Fabrication Principles, S. K. Ghandhi points out that The MOS transistor is the most promising active component for silicon VLSI circuits at the present time. There are a number of reasons for this choice. First, it is self-isolating, so that devices can be placed side by side on a chip without the need for providing isolation tubs. As a result, it is considerably smaller than its bipolar counterpart. 14.3 If the introductory element is not a main clause and a comma is not required, follow it with no punctuation at all. 15. Punctuating Indented Lists The items in a vertical list may be preceded by bullets or sequential numbers, or they may stand alone. The following devices can be modeled in PSPICE: resistors capacitors inductors diodes BJTs JFETs MOSFETs The advantages of BiCMOS are 1. the quiescent dissipation is very low; 2. the packing density is very high; and 3. high off-chip data rates are possible. 19
- 20. 16. Question Marks Use a question mark at the end of an interrogative element within or at the end of a sentence. Why am I studying chemical engineering? she wondered. 17. Exclamation Points Use exclamation points sparingly; too many of them will blunt your effect. 20