Tài liệu Guide for writing technical reports pdf

Guide for writing technical reports Swiss Federal Institute of Technology Lausanne EPFL-DMT-IMS, 2001 Guide for writing technical reports Guide for writing technical reports Guide for writing technical reports Preface Report writing is one of the many things with which EPFL students are confronted You may have the feeling that this is a nuisance; however, reports are of great importance for engineers The purpose of this guide is to help you, the student, with writing good reports While remaining compact, it combines basic advices and rules for lab experiment (TP), semester and diploma reports We emphasise that these are only guidelines As a consequence these rules should be applied with intelligence This is a modified copy of a manual that was made 20 years ago by teachers in Holland, with a few additions from other sources It has been adapted, we hope, to the tastes and opinions of the teachers here Suggestions for improvements, from teachers and students, are welcome Harald van Lintel Raphael Holzer Pierre-André Besse Lausanne, March 2001 v.1.1, 7/03/01 HvL Guide for writing technical reports Table of contents THE AIMS OF A REPORT STRUCTURING A REPORT 2.1 Laboratory reports (TP) 2.2 Semester and diploma reports LAYOUT OF A REPORT 3.1 Basic layout 3.2 Numbering 3.3 Tables 10 3.4 Graphs 11 3.5 Number presentation 12 3.6 Literature list and citations 13 LANGUAGE ASPECTS 14 4.1 Concise and simple sentences 14 4.2 Short words and active verbs 14 HOW TO GO ABOUT WRITING A REPORT 15 5.1 The basis 15 5.2 Realisation 15 Guide for writing technical reports The aims of a report The purpose of a report is to transmit coherent information on a subject to the target readers Reports at the EPFL are usually technical and should be based on verifiable facts or experiments You should write the report in such a way that it will be as easy as possible for the reader to understand, and eventually to apply the information in it It is not a history of your work Obviously, the requirements of your readers (and tutors especially) must be taken into account: what information is requested, how much does the reader know already, what interests him/her? Your report should be written in such a way that your fellow students will be able to understand it • In a laboratory (TP) report you must show that you are able to put order and coherence in your measurement results, that you have insight in the accuracy and reliability of the measurements and that you are able to link the experiment to the related theory • Semester and diploma reports often are part of a project The success of the project may be influenced by the quality of the report A clear and critical problem description and a well-motivated solution form an important contribution to the goal to be reached Often a report is the starting point for a next phase in the project Therefore, a thorough description of the experiments and results are important, as well as clearly formulated conclusions The teacher or tutor who has to judge the report will certainly appreciate it when the contents are clearly the intellectual property of the writers Copying someone else’s work is not appreciated! Guide for writing technical reports Structuring a report 2.1 Laboratory reports (TP) In general, depending on the type of experiment, for your “Travaille Pratique” report you may use something like this: • Title • Purpose of the experiment • Theoretical background • Description of the experiment • Results of the experiment • Calculations • Discussion of results • Literature • (List of symbols) • Appendices (may be put ahead of “Literature”) Answers to questions in the TP instruction are to be integrated in the report in the appropriate places Hereunder follow some clarifications and details in relation to the above example layout 2.1.1 Title Every report must be clearly recognizable by its title The title is here a compact description of the experiment This title appears on a title or cover page, that also should contain the following information: • Names of the authors • Class, affiliation • Date 2.1.2 Purpose of the experiment Describe in detail the purpose of the experiment and try to touch the heart of the matter 2.1.3 Theoretical background Explain shortly the background, preferably using consulted literature You should include short derivations of non-standard formulas in the main text 2.1.4 Description of the experiment Here the experiment or practical training is described You should include things as: • Description of the measurement equipment Guide for writing technical reports • The way the experiment is done • Particularities of equipment or materials It is in most cases not useful to go in great detail about the equipment; eventually you may refer to manuals and type numbers Don’t mention details that are useless Use appendices 2.1.5 Results of the experiment Describe the results you obtained, your observations, and how you dealt with unexpected problems Often the results include sequences of numbers that can and should be shown in tables or graphs Don’t forget to indicate measurement accuracies where useful Also other types of information, such as oscilloscope images and photos are experiment results 2.1.6 Calculations Here belong: • Calculations, where needed incl accuracy calculations • Extractions of measurement results from graphs In case of a number of identical calculations you only need to show one calculation example Clearly indicate to which measurement it applies The results can be collected in tables 2.1.7 Discussion of results This may be the most important part of the report, as from this should become clear what meaning and relevance the results have and what conclusions can be drawn from these Where possible, compare the results with theoretical predictions or literature sources (give the value and the source!) Discuss the differences Try to reach clear conclusions 2.1.8 Literature Give here an overview of consulted literature 2.1.9 List of symbols In case you make use of many symbols, it is good to add a list of symbols as well 2.1.10 Appendices In the appendices you can put items that would interfere with the logic and readability of the report, such as big tables (or too many), graphs or derivations, and items such as computer print-outs, program code, process lists, data sheets and detailed component descriptions Make sure that the reader will not have to jump much to-and-from the appendix We also want you to add all your original notes of the main experiments here Guide for writing technical reports 2.2 Semester and diploma reports Both types of report transmit relevant information, understanding and know-how that you developed during the project This should be exposed in a coherent, scientific way In practice there is often not much difference between them, so the layout can be similar: • Title • Table of Contents • Summary • Project description • Introduction • Body of the report • Conclusions • Literature list • List of symbols • Appendices (may be put ahead of “Literature”) Some clarifications: 2.2.1 Title The title should indicate in a few words the subject and the way it is approached Example: a title like “Silicon microfluidics” is insufficient “Silicon microfluidic sensors” is better but lacks information on what has been done A better title is for example “Fabrication and test of silicon microfluidic sensors” However, a title like “Realisation and test of a novel microfluidic sensor” is more appealing On the title page belong as well: • Name of writer • Time period or date • Institute where the work was done • Names of professor, assistants 2.2.2 Table of contents The chapters and sections (and if you like, subsections) are mentioned with their page number 2.2.3 Summary Mention for who the report is primarily made Inform the reader about the purpose, used methods and results; give the main conclusions and recommendations (about half a page) Stress the novelty and possible impact Guide for writing technical reports 2.2.4 Project description The description as formulated at the start is to be given here 2.2.5 Introduction Here you can indicate in more detail the purpose, background, starting points and limitations Explain briefly your approach and what is new In order to get the attention of the reader, it is good to write „top down“, i.e mention the main achievement already in the introduction 2.2.6 Body of the report This will be split up in several chapters, depending on the work that has been done Nevertheless, the body should be logical and fluent Transmit your message in the form of coherent information, not as a historical description In accord with the point of depart as formulated in the introduction, you should build up the subject matter in a logical way All matter that you feel should be in the report but does not fit with that logic has to go to the appendix Where appropriate you can refer to that in the text Examples of items that may be put in the body of the report: • Theoretical background • Reasons, motivations for design choices • Key design or layout • Key aspects of realisation • Choice of measurement method or set-up • Discussion of results • Anything else that the project description requires 2.2.7 Conclusions Give all relevant conclusions, even negative Stress novelty and scientific or industrial impact Also new insights, outlook and recommendations for improvement should be put here However, not introduce results or concepts that belong in the body of the report Bring structure in your conclusions 2.2.8 Symbol list Every report with a large number of symbols benefits from a symbol list You should have all used symbols in alphabetic sequence (small letters, capital letters, Greek) Indicate both meaning and units Try to adapt generally used symbols, and try to avoid the use of the same symbol for different meanings Also non-standard abbreviations can be added here 2.2.9 Literature list See section 3.6 Guide for writing technical reports 2.2.10 Appendices Hereunder fall things that would interrupt the fluidity of the body of the report, such as: • Long derivations of formulas • Calculations that would interrupt the body of the report (keep them compact) • Large tables with measurements or calculated results • Large drawings and schemes or layouts, series of pictures • Part lists • Computer simulation print-outs (listings, runs) • Partial copies of articles The report without the appendixes must be understandable and contain all important information Guide for writing technical reports Layout of a report 3.1 Basic layout Use A4 paper In long reports, start each chapter on a new page Use large margins (ca cm left margin, top and bottom) Preferably put explaining text next or under pictures, especially in semester and diploma reports Group the information in paragraphs On the cover, put title, names and date 3.2 Numbering 3.2.1 Chapters and sections We advice the use of a decimal enumeration system, such as used in this manual Thus: Title of chapter Title of chapter 2.1 Title of section 2.1.1 Title of sub section 2.1.2 Title of sub section 2.2 Title of section Use the same code in the table of contents (can be done in an automatic way with programs like Word) Don’t include Summary, Appendices, Literature list or Symbol list in this numbering 3.2.2 Formulas Essential formulas and formulas that are referred to in other places in the report must be numbered For example: f = s/m If you not have many formulas (say less than 20), you can use this type of numbering; otherwise you can use (3.1) etc., referring to the chapter the formula is in 3.2.3 Tables Tables should be numbered, and indicated: Table 1, Table (or Table 3.1, Table 3.2) 3.2.4 Figures All graphics that are placed in-between the text, such as drawings, graphs, pictures are called “figure” You can number them Figure1, Figure etc (or Fig.3.1, Fig.3.2) Together with the numbering you give a short and clear description (figure caption) This should be self-explaining: all the relevant information has to be in the figure or in the figure caption State clearly what is shown: “Measured…”, ”Simulated…”, ”Theoretical…”, ”Comparison…”, … The figures are placed close to the related text (1) Guide for writing technical reports 3.2.5 Appendices If you have only a few: Appendix A Tables of expansion coefficients Appendix B Specifications of current amplifier SRS 570 If you have many that can be grouped into types: Graph A First DC current measurement Graph B First AC current measurement Mask Back side Mask Front side Mask Metallisation You indicate these in the Table of Contents as: Graphs Mask layouts 3.3 Tables • Put above or under the table a description: Table 2, “short description” • Better not to make horizontal tables: such save space but are difficult to read Thus not: U [V] 2.00 4.00 6.00 8.00 10.00 I [mA] 0.4 2.7 4.2 5.3 5.5 5.6 But like the following (with the cause in the left, and the result in the right column!): U [V] 0.4 2.00 2.7 4.00 4.2 6.00 5.3 8.00 5.5 10.00 • I [mA] 5.6 Shift repetitive information from the columns to the heading In the heading above each column you mention: o The contents, often using a symbol (e.g U) o The unit between brackets (e.g [mV]); choose the unit to be convenient in size, e.g 13.6 mV instead of 0.0136 V (only use brackets [] where needed!) o The precision, if this is of importance and similar for all values • Try to shift as much as possible information from the heading to the description • Choose the sequence of columns in a logical way (put together what belongs together) 10 Guide for writing technical reports • Don’t put very long or wide tables in the text if not necessary It is better for the reader if you put them in an appendix or split them up in smaller tables Avoid that tables continue from one page to another 3.4 Graphs 3.4.1 Axes a Horizontally (x) you put the independent variable (the cause) and vertically (y) the dependent variable (the result)!! For example, if you measure the resistance as function of the temperature: then you put the resistance on the vertical axis But if you measure the temperature as function of a heater resistance, you put the temperature on the vertical axis b The divisions on the axis depend on the following: o The space should be used efficiently o Usually the axes go preferably through the origin (0,0) o If you don’t start at 0, it’s good to show it (but cumbersome with Excel): o Please divide the axes in multiples of 1, 2, 5, 10 (etc.) units (“ticks”), not put them every or units! Add enough (not too many) values o Consider the use of logarithmic divisions; realise what is useful and/or common c Near the axes you indicate the variable (preferably a symbol) and the units: e.g I [mA] or t [s] Near the vertical axis you put the comment horizontal or, if there is lack of space and you place it vertical, it should be readable from the right Don’t forget to describe what exactly is plotted as function of what d Use exactly the same layout for two results that you want to compare (identical axes) 3.4.2 Measurement points • Include all measurement points, also the ones that seem to be out of range Make them sufficiently large to see them after you draw a line through them • Make sure when you the measurements that the points will be well distributed Where the graph behaves strangely (resonance peaks and so on) there should be more points (hopefully you realised that when doing the measurement!) • Often it is useful to indicate an estimation of the inaccuracy using error bars (especially when large) 3.4.3 Lines • Ideally you draw a smooth line without trying to exactly force them through all points, in accord with theory (expectation) and common sense (error bars are 11 Guide for writing technical reports helpful for that) With automated programs like Excel that may be a bit problematic In some cases it is not beneficial to draw a line at all • Use different line styles, especially for lines that are close together or have a different meaning, such as theory and measurement (solid, dashed, ) • If theory predicts that the points lie on a straight line, draw a straight line as good as possible through the points If theory predicts the line to go through the origin, show the origin in the graph Depending on the circumstances, it may be a good or a bad choice to force the line through the origin (comment on it in the text if you think there is an offset of some kind) An example of a bad presentation (Fig.1) and a good presentation (Fig 2) is shown hereunder: 200 Evaporation rate [nl/s] + 190 170 150 Evaporation rate[nl/s] 150 100 130 110 90 50 70 0 50 50 100 150 200 250 300 350 400 450 500 Fig.1 First results 100 200 300 400 500 Power [mW] P[m ] W Fig.2 Measurement of evaporation rate as function of input power (third order fit) 3.5 Number presentation In general you should not give more and not less decimals than what is meaningful or useful A calculator usually gives too many digits! How many you should take into account or present depends on: • The specifications of the equipment, either explicit (specifications) or implicit (number of digits, instability, time since last calibration (!)) • In calculations it is important how the inaccuracies influence the end value It is wise to use at the start of calculations more digits than seem required or relevant, to prevent rounding errors Watch out for dependence between errors: for example some systematic errors may have no effect on your result Then one digit “too much” may be relevant after all! Often an estimation of the accuracy (error) is useful In further calculations you should not forget that you started with an estimation In many cases a simple, so-called “worst-case” calculation will be sufficient Such a calculation is valid for correlated or non-statisical errors If applied to all errors, it easily results in overestimation (which can be acceptable) 12 Guide for writing technical reports Some rules for worst-case calculations: • Additions and subtractions: add absolute errors • Multiplications and divisions: add relative errors (%) • Square root: half the error • If you don’t know or are not sure, calculate the extremes (sin x, ln x etc.) If you have large independent errors of a statistical nature, you should sum the squares of the errors instead, according to standard deviation theory 2 Thus: Error = E1 + E + with Ex= error As above, work with absolute errors for additions, and relative errors for multiplications Note that the estimated error Ex is usually defined as twice the Standard Deviation, which corresponds to a 95% certainty interval (sometimes a larger interval is taken) When you present values: • Use prefixes (kV, mA, pF) or powers of 10: preferably multiples of 1000 (10-6, 109 etc.) • Indicate absolute errors in the same unit and power of 10 • Indicate the number of relevant digits Some examples: 4.0872 +/- 0.1 2.1 +/- 0.3 % 0.845 +/- 1.728 % should be: 4.1 +/- 0.1 should be: 2.100 +/- 0.3 % (or: 2.1 +/- %) should be: 0.845 +/- 1.7 % 3.6 Literature list and citations A pleasant way of citing literature is to mention the name of the first author, e.g “The measurement method as used by Ott [13] …” In case you refer to a book or other voluminous work, also indicate page number or chapter Group the list alphabetically on name of first author, and chronologically for the same author • Books: Names of authors, book title, edition (if not first), place, year, volume number, first and last page you refer to • Journal articles: Names of authors, article title, place, name of journal, number, year between brackets, volume number, first and last page of the article Note: In case of more than two authors you can put “et al” 13 Guide for writing technical reports Language aspects 4.1 Concise and simple sentences The writing style should be precise, clear and scientific Long sentences are more difficult to understand than short ones and risk tiring your readers Avoid unnecessary words You should have less than 20 words per sentence on the average; avoid more than 35 words in the longest sentence Sentences like this last one (separated by ; or : ) are counted as two Avoid too deeply nested sub-sentences A horrific example: “The differential equations, the solutions of which that must be solved with eight constants, to be derived from the boundary conditions, are known, have been derived” However, even short phrases can be difficult to understand Try to avoid the so-called overstressed construction, which happens for example when too many words are squeezed in-between the subject and the related verb Keep related words together Instead of: The lab equipment that we borrowed from the IOA turned out to be useless for our purpose Better: We borrowed lab equipment from the IOA, but it was useless for our purpose Also, be to the point: keep unnecessary words and repetitions to a minimum Not: “By slow and careful evaporation of water we perform the needed dehydration until it is dry.” Better: “We dry it slowly.” 4.2 Short words and active verbs Sentences can be tiring because of too many long words If you spot such, try to replace some words by shorter synonyms Scientific articles and scientific books are usually written in an impersonal style as this gives a modest and “objective” (neutral) impression It is common practice not to use “I”, and rarely “we” Sentences tend to use the passive form as a result For example: instead of writing “I investigated the influence of a higher viscosity on the layer thickness”, people tend to write “The influence of a higher viscosity on the layer thickness was investigated” However, now it is not clear if the author did it, someone else, or another group! To convey the same information it should be “The influence of a higher viscosity on the layer thickness was investigated by the author”, which is a bit heavy A trick some people use is: “The author investigated the influence of a higher viscosity on the layer thickness” In lab reports you can be more personal Often a sentence can be changed from the passive form to the active form by rearranging the words Instead of “The pull strength was doubled by the addition of 3.6% wolfram”, you can simply write: “Adding 3.6% wolfram doubled the pull strength” Also, instead of: “Water condensation is likely to occur in the narrow gap” it is better to write: “Water may easily condensate in the narrow gap.” 14 Guide for writing technical reports How to go about writing a report 5.1 The basis It starts with clear and complete notes that you take during your work For semester and diploma work this means you should keep a well-organized notebook in which you put all things (or copies) that relate to your task: study, notes, designs, discussion notes, measurements, calculations, failures, graphs etc During this time you should already work out and discuss some of your material for inclusion in your report, and contemplate on how you will present your work 5.2 Realisation There are many ways to it, but what follows is, we think, a useful suggestion of how you can it a First phase: inventory b Write on a large piece of paper all main items that you must include in your report Check the TP/project description and your notes to see if you forgot something c Second phase: order and selection (see ch.2) Make a draft chapter division Try to include all the main items in these chapters, and adapt them if needed Order the chapters and items in a logical way Do not hesitate to put at the beginning what you did at the end if it makes more sense a Third phase: write your report (see ch.3 and 4) b Fourth phase: checking Carefully read your report from start to end You may also ask someone else to examine it and comment on it 15 .. .Guide for writing technical reports Guide for writing technical reports Guide for writing technical reports Preface Report writing is one of the many things... HOW TO GO ABOUT WRITING A REPORT 15 5.1 The basis 15 5.2 Realisation 15 Guide for writing technical reports The aims of a report The purpose of a report is to transmit coherent information on a... else’s work is not appreciated! Guide for writing technical reports Structuring a report 2.1 Laboratory reports (TP) In general, depending on the type of experiment, for your “Travaille Pratique”