Writing Technical Reports

1. Writing Technical Reports Prof. Dr.-Ing. Reinhard German Friedrich-Alexander Universität Erlangen-Nürnberg Informatik 7 (Rechnernetze und Kommunikationssysteme)

2. Writing for Engineers • Sir Francis Bacon, Essays, 1597 • “Reading makes a full man; conference a ready man; and writing an exact man.“ • Translated in our context • Reading, discussing and writing are essential aspects of communication for the practicing engineer. • Also true • Writing is probably that part of an engineer‘s working life which he most dislikes. Unfortunately, the more successful he is in his profession, the more time he will spend pen in hand, or, nowadays, at the word processor.

3. Outline • Structure of a Technical Report • From Idea to Paper • Vocabulary • Sentences and Punctuation • Paragraphs and Format • Good Style • The Presentation of Written Information

4. Structure of a Technical Report • Title, author(s), affiliation • Abstract (a short summary) • Table of contents (only in larger reports) • Introduction • Core of the report (several chapters) • Conclusions • References • Index (only in larger reports) • Appendix (optional)

5. Structure of a Technical Report • Introduction • Why and what for (four)? • Why is the topic of interest? • What (1) is the background of the previous solutions, if any? • What (2) is the background of potential solutions? • What (3) was attempted in the present effort? • What (4) will be presented in the paper? • Make curious and motivate • Many readers will only browse through this part of the report

6. Structure of a Technical Report • Core of the report (several chapters) • Detailed description of • Problem • Background, methods and approaches • Results • Discussion • Consequences

7. Structure of a Technical Report • Conclusions • Concentration of the results, contributions • Retrospective discussion of results • Put results in larger context • Discuss possible further work • Many readers will just browse through introduction and conclusions

8. Structure of a Technical Report • References • Always give references to the sources your work is based on • Simple numerical scheme is sufficient for most reports: • Citation in the text: “[1] gives hints for good style of technical reports.” • In the list of references:[1] J. van Emden. A Handbook of Writing for Engineers. Macmillan Education, Ltd. • The list of references can be sorted alphabetically or by occurrence in the text • The reference must contain full and accurate bibliographical details: authors, title of the work (article and name of book), publisher, publication date, and should be consistent in form • If the information is only available in the Web, give URL and authors, possibly combined with date when you accessed it • Plagiarism is a serious misbehavior

9. Structure of a Technical Report • Appendix • Technical details can be shifted in appendices, if they would overwhelm the core of the report • Readers can access this information if appropriate • E.g., curves, data collections, tables, specifications, proofs, manuals • Source code • Appendix is a good place • Sometimes appropriate to discuss software architecture and key parts of the software in the core of the report • Footnotes • Play a similar role as appendices, if the additional information is shorter, but should be avoided

10. From Idea to Paper • Questions to ask at the beginning and during writing • Who is my reader/are my readers? • How much does the reader know about this subject? • Why does he want to read this document? • What do I want to tell him? • What result do I want from his reading of my document?

11. From Idea to Paper • Top-Down strategy • Collect first and structure afterwards • Collect information • Make a patchwork of ideas, information pieces, phrases, etc. • Structure these fragments • Make a table of contents • Write the chapters • A clearly structured document will generate reader goodwill • Do not begin at the beginning • The first sentence or paragraph is almost always the most difficult • Choose a simple factual section you feel comfortable with

12. From Idea to Paper • Writing is an iterative process, the final result is approximated step by step • (re-)structure, (re-)write • (wait) • Read printout, also other persons • if not satisfactory, goto 1

13. Vocabulary • Use words which the reader will understand • Cultural background, technical level, ... • Use simple words as far as the context permits • E.g., „to tell a reader“ instead of „to acquaint reader with“ • Clichés and slang should be avoided • Lifeless phrase: „at this moment in time“ • Slang belongs to casual conservations between friends • Professional jargon must be shared with the reader • Before usage specific vocabulary and abbreviations must be defined, put them in italics in this definition • “The event list is a data structure with ...”, “Alinear congruential generator (LCG) is a...” • Try to introduce acronyms locally or use a table if there are too many • Popular jargon should be avoided • Pompous words without much meaning • “A constant flow of effective information will maximise the probability of project success and minimise the cost and time required for standardisation of anticipated documentation.”

14. Confused and abused words Access, assess Advice, advise Affect, effect Alternate, alternative Ante, anti Bad, badly Bi, semi Can, may Capital, capitol Complement, compliment Comprise Contact Continual, continuous Council, counsel, consul Discreet, discrete Disinterested, uninterested Emigrate, immigrate Eminent, imminent Farther, further Fewer, less I, me, myself Irregardless It‘s, its Lay, lie Like, as Loose, lose Meantime, meanwhile People, persons Predominant, predominate Principal, principle Shall, will Stationary, stationery That, who, whose Was, were Who, whom Vocabulary

15. Sentences and Punctuation • Definition of a sentence • A sentence is a group of words which makes sense in itself • A sentence contains one item of information to which various subsidiary ideas may be attached • A sentence should contain at least one complete verb • Engineers often tend to write longwinded chains • Bad: “When you have logged into the computer and typed in your user name, the computer will respond with a dollar prompt, you can then set your password by invoking the `passwd´ command, this password should be used whenever you log in in the future.” • Better: “When you first log into the computer, type in your user name and the computer will respond with a doller prompt. You can then set your password by invoking the `passwd´ command. This password should be used whenever you log in.”

16. Sentences and Punctuation • Another example • “For higher power applications chopper drive which is more efficient but more complex than dual voltage drive which requires two supplies must be used although it is complex, generates audible noise at the chopping frequency possibly causing interference and additional iron losses in the motor.” • “For higher power applications, dual voltage drive or chopper drive must be used. Dual voltage drive is simpler than chopper drive but is less efficient and requires two supplies. Chopper drives are very efficient but complex, generating audible noise at the chopping frequency and possibly causing interference and additional iron losses in the motor.”

17. Sentences and Punctuation • Simple sentence: one idea • Compound sentence: more than one basic idea • Sentence length • Should not be so long that the reader is unable to assimilate the data • 17-20 words is reasonable, 40 words is sensible • Variety in sentence length helps the reader • The main unit of a sentence conveys the main idea, and must be readily identified by the reader • Start the sentence with the most striking idea • Plan the sentence so that it says what it means in a positive way

18. Sentences and Punctuation • Semicolons ; • If two sentences are closely related in subject matter, the relationship can be stressed by joining the sentences with a semicolon • Commas , • Separate main part of a sentence from subordinate part • Difficult: obey rules but also “feeling” of language • If in doubt, read the passage aloud and notice where the voice pauses naturally. Mark the place with a comma. • “Quotation marks” • For text fragments from other sources • English form: “quotation marks” • German form: „Anführungszeichen“ • For emphasizing text fragments, bold face or italics are a better choice

19. Paragraphs and Format • Definition of a paragraph • A paragraph is formed from a series of ideas, united by theme and creating an organised structure • Impossible to follow logical flow of ideas without paragraphs • Paragraph length • 3-6 paragraphs on a page • Font, size and line length • In written text, Antiqa-fonts (those with serifs) have been used for more than 2000 years, usually “times” in word processors, still a good recommendation • Helvetica (without serifs) can appear dry in longer texts, good for presentations • 10–12 point, no smaller than 9 point (1 pt = 0.375 mm) •  60 letters and spaces, 10-12 words • Leave space on the page to allow the text to stand out clearly • Default settings of Latex are a good hint

20. Paragraphs and Format • List information whenever it is possible to do so • Not so easy to understand:“Preventive maintenance should be considered when the time interval between equipment breakdown can be predicted with reasonable accuracy, or when the cost of preventive maintenance attention is less than the repair cost when both costs include that of any lost production. It may also be appropriate when equipment failure is likely to disrupt subsequent production operations or cause customer dissatisfaction. A particularly important application is in cases when injury could result from equipment breakdown.”

21. Paragraphs and Format • Organized as list of items:“Preventive maintenance should be considered when the following conditions apply. • The time interval between equipment breakdown can be predicted with reasonable accuracy. • The cost of preventive maintenance attention is less than the repair cost when both costs include that of any lost production. • Equipment failure is likely to disrupt subsequent production operations or cause customer dissatisfaction. • Injury could result from equipment breakdown.”

22. Paragraphs and Format • Set out numbers in a way which is easy to use • “It is interesting to note that between January 1986 and March 1986, 1350 pcb were produced with nine operators, while between January and March 1987, seven operators produced 2869 pcb.” • “January-March 1986: 9 operators produced 1350 pcb January-March 1987: 7 operators produced 2869 pcb”

23. Paragraphs and Format • Numbering and headings of sections • 7 chapter heading • 7.1 section heading • 7.1.1 subsection heading • Do not use more levels • Bold face and decreasing size • Always add text after a heading and announce the contents of the chapter/section/subsection • Figures and tables • Sequential numbering of both • Figures with a subtitle • Tables with a title at the top • Always an explanation in the text! Figure 23. An example of good GUI design.

24. Paragraphs and Format • Mathematical formulas • there are international conventions from the ISO: • Variables: italics • Non-scalars (vectors, matrices): bold face • Functions, constants, numbers, symbols, parantheses, …: not in italics, not bold face • E.g.: y = 3x1 + 4x2 • Also conventions for units of measurements and abbreviations • I do not use italics in presentations but in texts • Also important: use simple formulas and common symbols as in related literature

25. Paragraphs and Format • Objective of the report • Reports are written for their readers • Most reports convey information (e.g., about a simulation project) or are a request (for more time, money, ...) • Language should be used formally, but in an easy, fluent way, as precisely as possible • The objective must be clear, the report must give a clear picture of the situation • Some reports are read from start to finish • Far more reports are used: the reader picks sections which are of interest • The structure of the whole document must be immediately apparent to help the reader to navigate through it

26. Good Style • Good style has its ABC: accuracy, brevity, clarity • Use the active voice rather than the passive, if possible • Use verbs • Diagrams should support and not interrupt the message • A well-chosen example helps the reader‘s understanding and gives life to the text • Avoid abstract words as far as possible. Use simple, direct language • Gender neutrality (usages of he/she etc.): do you like it?

27. The Presentation of Written Information • All documents should be checked for factual accuracy • All documents should be checked for typing accuracy • A document should look both attractive and professional; it should inspire confidence • Danger to overdo the layout

28. References • J. van Emden. A Handbook of Writing for Engineers. Macmillan Education Ltd., 1990. • J. Venolia. Wright Right! Ten Speed Press. 1988. • Slides from Prof. B. Haverkort, Univ. Twente, about writing seminar papers, in turn based on • G. D. Ulrich. Write a god technical report. IEEE Trans. Prof. Comm., vol. PV-27, no. 1, pp. 14-19, March 1984. • E. P. Papadakis. Why and What for (Four): The Basis for Writing a Good Introduction. Materials Evaluation, vol. 41, pp. 20-21, January 1983. • P. Rechenberg. Technisches Schreiben (nicht nur für Informatiker). 2. Auflage, Hanser Verlag, 2003.