ETHZ
Institut für
Energietechnik
Laboratorium für
Kerntechnik
Prof. G.
Yadigaroglu a
April
2001
How to Write a Good
Report
[Ratschläge zur Abfassung eines guten Berichts]
This
text attempts to give some guidance on how to write good technical reports b and to prevent the most currently
occurring mistakes. Ask yourself a few simple questions and perform a few
"checks" while you are writing; this can help you to better present
your work.
The
technical report presents the results of an investigation in an easily understandable [verständlich] and fully
traceable [nachvollziehbar] way. The
report should be comprehensive
[umfassend] and self-contained [in
sich geschlossen] to the extent practical (judgment is needed here. if not sure
ask your advisers).
Generally,
the report is addressed to persons who have the same background as the person
writing it (in our case, engineers or scientists). It should be understandable
by persons who did not follow the development of the work (it is not written only for a professor and your
advisers who followed your work).
The
report should not be written in principle as a "diary" or "journal"
of your work tracing its "historic" development. The report should present
the final outcome of the work, the
final product. A description somewhere in the report of the historic
development of the project may in certain cases be useful, to show for example
why certain decisions were taken. The emphasis should, however, remain on
presenting the final outcome, while explaining the reasons that led to it.
Organization of the
Report [Gliederung
des Berichts]
The
report should have the following parts:
Abstract
or Summary [Zusammenfassung oder Inhaltsangabe]
The
Abstract is a self-contained,
independent, part of the work. (It may be the only part of the report
“abstracted” in electronic data banks, etc.) The Abstract should be between 10
and 50 lines long, depending on the importance of the report. It is independent of the main report and
vice-versa. The Abstract helps the reader who is in a hurry learn what the
report contains. It is not an
introduction to the work; it is intended for a reader already somewhat familiar
with the subject of the report. It should convey as much information as
possible about the particular method followed and the main findings/conclusions
of the report.
Table(s) of Contents
It
is particularly necessary for long reports. It provides a good way of finding
the relevant sections of the report and gives an overview of the work. (Tables
of tables and of figures can also be added).
Introduction [Einführung]
The
following are typically included in the Introduction:
· the
background [Ausgangslage] that
motivated the work is briefly presented (Example: it has been observed that car crashes often lead to injury of the
passengers who are projected forwards - therefore a system cushioning their
impact could help: we are designing an air bag).
· previous work
in the same or neighboring areas is mentioned. (Example: air bags have been discussed in the important paper by Benz (1993)..., or ...were the subject of the previous Diploma
project by Ethgenious (1992)). Here you may add the important conclusions
or results obtained by previous investigations and/or the way these were
presented, mentioning their limitations, as well as your own critique.
(Example: Ethgenious (1992) presents
interesting plots of damage to the head as function of air bag size; his
results are, however, limited to air bags of older design.)
· the
definition of the problem is given, i.e.
what exactly we have undertaken to study and which results we seek (Example: we are designing an air bag capable of
protecting adequately the head of an adult passenger; the bag should have the
following characteristics...)
· the
contents of the report may be
briefly summarized (Example: in Chapter 2
we summarize the general theory needed to understand air bags. Chapter 3
proposes various design alternatives,...)
Main body of the
report [Hauptteil
des Berichtes]
Your
work should be presented in a concise (not unnecessarily long), logical, clear
and traceable way.
Presentation of the
work: Describe the experiments conducted, the
theory developed, or the computations performed.
Discussion of the work:
Discuss what you found. For example, what you learned by examining the various
figures that you produced, or why a certain design alternative was found to be
preferable, or why your theory failed at some point to describe some
experimental observations. To the extent possible, make comparisons between theoretical
predictions and experimental results (best on the same plot).
If
you are not sure about certain findings, but have good reasons to believe that
they are likely to be correct, you may still include your ideas, but you should
use words like “these findings suggest that” or “it is conjectured that,” or
“we are (fairly) confident that” etc. to indicate the lack of full evidence. When you are not sure
about the reasons of certain discrepancies (what was missing in the analysis
and/or the experiments that could have produced the discrepancies) again, use
words like “these findings suggest that.”
Conclusions [Abschluss, Schlussfolgerungen]
This
is generally a rather short section summarizing the main findings [Resultate]
of the work and, as applicable, their implications [Bedeutung]. Recommendations
for future work may be made here (“Conclusions and Recommendations”). The
conclusions should, in principle, not contain statements not supported from material included in the main body of the
report.
In
a long report, you may wish to have conclusions at the end of each chapter and
a summary of these in the general Conclusions chapter at the end.
The
reader not interested in following the details of your work (or unable to
understand them) should be able to profit from your findings by reading only
the Introduction/Statement of the Problem and the Conclusions.
Acknowledgments [Verdankung]
These
are to thank those who helped you, provided unpublished results, financial
assistance, gave permissions to do certain (possibly unusual) things (e.g., use
a machine in another institute), etc.
Nomenclature
and Abbreviations [Nomenklatur und Abkürzungen]
Define
all symbols and abbreviations used in the report (if not already done in the
text after their first appearance, or in addition to the text). This section
can also be placed at the very beginning of the report.
References [Literaturangaben]
Listing
of the published works that you used. References should be complete (the
"traceability" principle: any reader should be able to find them).
See examples below.
Should
contain only the works cited in your text and not other publications. If you wish to mention some other useful
sources of information (to help, for example, future work: either include them
here as "Additional Interesting References" or manage to make a
global reference to them in the text
(Example: Additional information
on this subject can be obtained in Refs. [23-28]).
Appendices [Anhänge]
Appendices
contain information or data that are needed for completeness but can be skipped
during a first reading of the report. For example, all the actual data
collected (and how/where they have been stored, if necessary), or the long
derivation of an equation used in the report, or the materials properties used
in your analysis and their sources. The Appendices should be numbered and
referred to in the main body of the text (the reader is not expected to go find
things in the Appendices himself).
Facts, Opinions,
Traceability [Tatsachen,
Meinungen, Nachvollziehbarkeit]
A
clear distinction should be made between facts and opinions. Opinions should be
kept to a minimum (unless you are clearly writing an "opinion
paper.")
All
facts reported should be based/supported by either:
· experimental
evidence gathered, theory developed, or calculations performed during your
project.
· "references"
or "citations" to previously published work (journal articles, other
reports, books, etc.).
When
unpublished information must be used, it is referenced as "personal
communication." (Example: the unpublished results of a previous experiment
that were made available to you.)
Only
things that are normally known to every person to whom this report is addressed
and are well accepted (e.g., Newton's law of gravity, the conduction equation,
etc.) need not be referenced. Typical wording: Using Newton's law of gravity...
If
an unusual expression of a well known physical law is used, however, it is
still necessary to cite a source for it (e.g., a standard, generally available
textbook. Example: using the following
form of the mass conservation principle (Baer, 1999)...). In general, avoid
citing "Vorlesungsunterlagen" - you are not writing only for the
persons who have followed the same courses.
The
reader should be able to clearly distinguish between new information generated
from your work and already available information repeated in your report; this
is accomplished by proper wording. Typical examples:
- in our experiments we
observed that.../ the experimental work has shown that...
- our calculations
show... /the calculations outlined above have shown that...
- during this study we
found that...
Only
when the source of the statement is obvious from its context, one does not need
to identify its origin. For example, each step of a long derivation does not
need identification.
Any
statements that are not findings or facts (as defined above) should be clearly
identified as such with proper wording. Examples:
- in our opinion, red
air bags are not a good idea
- our experiments
strongly suggest that... (they do not prove
it, but we have good reasons to believe that it is true)
If
you follow the rules given above, all statements in your report should be
"traceable" to their origin, that is, your calculations or your
experimental measurements, or the published information that you used and
cited. A third person reading your report should be able to repeat or
reconstruct everything you did using only your report and information contained
in the references. Sufficient (but not too much) detail should be given in the
report for this purpose. (It may take the reader a long time to reconstruct
your work, but this should in principle be possible).
Where to put what. What to include in your
report
[Welches Material wohin gehört, was erwähnt und
was gegelassen werden soll]
The
new information that you generated should at least be summarized in the main
body of the report. If the main body is becoming too long and detailed, the
details can be put in Appendices. c
You
need not repeat all the background information necessary in your report,
especially if it is easily and clearly available elsewhere. Repeat only the
minimum necessary for making your report readable and to some extent
comprehensive and self-contained. (There is a difficult balance to be reached
here; if you are not sure, ask your advisers.) For example, you should clearly
not include the basic derivation of the conduction equation [Wärmeleitungsgleichung]
if you simply used it. (Such a derivation belongs to a textbook on heat
transfer.) The quality of your report
will not be improved by filling it with equations that are not needed; it will
not be judged on its length, but rather on its readability and importance of new information contained.
Style and format [Stil und Darstellung]
Your
style and format should be consistent throughout the report. (For example,
always write equation (1) or Eq. (1) but do not mix the two
alternatives.)
Use
either the first person (I/we performed
the following experiment...) or the passive tense (The following experiment was performed...) but avoid mixing the
two styles.
Use
simple language; don't try to
impress the reader with complicated sentences. Avoid (in English at least) long
sentences. Don't include any word or sentence that does not "bring
anything." (Ask yourself the
question: is this needed for better comprehension or clarity? does it "bring"
anything? - if the answer is "no," delete).
The
report should be readable "linearly,"
from beginning to end, without the reader having to go back and forth or
navigate between main body and appendices. In writing your report you may have
"clicked" back and forth, but don't expect the reader to do this.
Construct the report in a way avoiding excessive references to information
"given below." Remember that you are writing to convey your results
as "comfortably" as possible.
The
report should be logically subdivided
in chapters (or sections for shorter documents), sections, and subsections (of
more or less similar length) to help reading. Number the chapters, sections,
subsections, etc. in a logical way, preferably using a decimal system: Chapter
1, Section 1.1, Subsection 1.1.1, etc.
In
organizing the main body of the report avoid excessive “nesting” of the
sections, subsections, etc. (avoid section numbering with more than, say, three
digits: not more than 3.2.5). The titles of the various sections should be
meaningful and should apply to the whole contents of the section - do not
smuggle irrelevant material in a section because you do not know where to put
it. The number of subsections in a section should approximately reflect the
importance of that part of the report (e.g., do not create ten subsections for
the introduction and only a couple very large ones for the main body of the
report).
All
figures, tables and appendices
should be referred to or cited somewhere in the report. Don't expect the reader
to discover the appendices by turning the pages. Number figures, tables,
equations (if necessary) and appendices in their order of appearance in the
text.
All
figures, tables and appendices should have a descriptive title or
"caption" (not only Fig. X).
Keep the captions relatively short but use them to convey as much information
as possible. If possible, the figures and the captions taken together should be
self explanatory (for the person looking through your report).
Define
all symbols (and abbreviations) used
(especially unusual or non-standard ones) in the text following their first
appearance or in the Nomenclature
section.
References [Quellenangaben]
All
references and citations should follow a standard uniform format. The two main
recommended alternatives are:
Alternative
"brackets and numbers"
In
the text [1], [2] etc. (or superscripts1,2) in their order of
appearance (a pain!); numerically ordered listing in the References. Example:
Modern steam
generators produce steam at about 250 bar and 500 C [1]. Their superheater
tubes often suffer from a strange disease first identified by Ericson et al.
[2]. The main symptoms of this disease are cracks [3], loss of weight [4], and
....
References
1. F.
Author, Modern Steam Generators,
Pergamon Press, Paris (1998).
[Author(s),
Title of book, Publisher, City
published, (Year of publication)].
2. J.
Ericson, P. Smith and J. Johnson, "A Strange Disease Observed in Steam
Generator Tubes," Journal of Strange
Machines, 25 (11), 245-256
(1996).
[Authors,
"Title of Article," Volume (number), pages (year of publication)].
3. A.
Ethstudent, "A Beautiful Report on Cracks in Tubes," ETH, Institute
for Strange Research report ETH/ABC/356 (September 1997).
4. B.
Weightwatcher, "Loss of Weight in Tubes," ETH Dissertation No. 123456
(1999).
Alternative
"names and year"
In
the text the name(s) of the authors followed by the year of publication in
parentheses (makes the text a little longer); in the References section the
works ordered alphabetically (more convenient and useful).
Modern steam generators
produce steam at about 250 bar and 500 C (Author, 1998). Their superheater
tubes often suffer from a strange disease first identified by Ericson et al.
(1996). The main symptoms of this disease are cracks, as discussed by
Ethstudent (1997), weight loss discovered by Weigthwatcher (1999), and ...
References
Author,
F. (1998) Modern Steam Generators,
Pergamon Press, Paris.
[Author(s)
(year) Title of book, Publisher, City
published].
Ericson,
J., Smith, P., and Johnson, J. (1996) "A Strange Disease Observed in Steam
Generator Tubes," Journal of Strange
Machines, 25 (11), 245-256.
[Authors
(year) "Title of Article," Journal, Volume
(number), pages].
Ethstudent,
A. (1997) "A Beautiful Report on a Strange Disease," ETH, Institute
for Strange Research report ETH/ABC/356.
Weightwatcher,
B. (1999) "Loss of Weight in Tubes," Swiss Federal Institute of
Technology - Zurich (ETHZ), Dissertation No. 123456.
If
there are only two authors, cite them both in the text: Badguy and Goodguy (1998) or
(Badguy and Goodguy, 1998). For more than two authors use some Latin: Badguy et al. (1998) or (Badguy et al., 1998). In the
References section preferably list all authors.
Additional Recommended
Reading
The
following books (all available in the LKT Library) can help you improve your
writing:
·
V. Booth, Communicating in Science, 2nd edition, Cambridge Univ. Press
(1993).
·
R. A. Day, How to Write & Publish a Scientific Paper, 3rd edition,
Cambridge Univ. Press (1988).
·
D. Porush, A Short Guide to Writing About Science, Harper Collins College
Publishers (1995).
·
R. A. Rathbone, Communicating Technical Information, 2nd edition, Addison-Wesley
(1985).
·
C. H. Sides, How to Write & Present Technical Information, 2nd edition,
Cambridge Univ. Press (1991).
a The author is indebted to M. Andreani
and to H.-M. Friess for comments and constructive suggestions.
b Your comments to this
document regarding possible improvements will be appreciated; after all we are
trying to give guidance on good writing... Please mark your copy and return it
to the author.
c If you have collected important data
that should not be lost, it may be useful to state (e.g., in an Appendix)
where, how, and in which form these data were stored (a list of files and their
contents).