The K-Zone: How To Write A Technical Report
The K-Zone: How To Write A Technical Report
html
Summary
This article gives some general guidelines on writing a technical or scientific report. It describes the `standard model' of
report writing, and some alternatives. The article is intended for students who are currently undertaking undergraduate or
master's degree projects, or expect to do so in the near future.
Contents
Summary
Contents
1 Introduction
2 Fundamentals
3 The standard model
4 Alternatives to the standard model
5 Language, style and presentation
6 Visual material
7 Things to avoid
8 General guidelines
Bibliography
1 Introduction
The ability to write clear, concise reports is an asset to almost any professional. In this article I offer some general guidelines
on report writing, focusing particularly on something I call the `standard model'. This `standard model' is a formalisation of
the way that scientific reports have usually been written over the last fifty years or so. While the standard model has its
detractors, and is often used inappropriately, it still has a lot to recommend it. I normally suggest to students who don't have
much writing experience that they follow this model unless they have good reasons not to. In this article I will also try to
explain why we recommend that reports are written in a particular way.
2 Fundamentals
The main purpose of a technical report is to convey information. The report should place as few hindrances as possible
between the mind of the writer and the mind of the reader. A secondary function is to stimulate and entertain. There are
people -- a tiny minority -- who can inform and entertain at the same time. If, like most people, you have to make a choice
between the two, you should try to inform rather than to entertain. Of course, if you were writing a novel the priorities would
be reversed; but in report writing it is the information that is paramount.
A good report needs careful planning. As part of the planning stage you should try to answer the following questions.
What is the report about? What are you trying to say? You should arrange things so that they key facts and
conclusions are very accessible. Not everyone will read the whole report, so ensure that your message will get across
even if a person only skims the document. I have been told -- and tend to believe -- that senior managers have an
attention span of about four minutes. This suggests that if you are writing with these people as your audience, your
report should start with a summary that can be read in a few minutes. In fact, this is a good idea whatever the
audience.
Who are you writing for? It is simply impossible to write a technical document that will be equally easy for everybody
to read: the level of explanation you need for an expert audience is totally different from that needed for readers who
are unfamiliar with the subject. It is absolutely essential that you identify the potential readers -- the professional
1 of 9 05/03/2009 14:01
The K-Zone: How to write a technical report http://www.kevinboone.com/PF_howto_report.html
group, not the individuals -- before you start work. In the university environment your report will probably be read by
lecturers. These people will have a good knowledge of their subject in general, but will probably not know much about
the precise field of your report. You should always bear this in mind. If you are writing for computer scientists you
don't need to explain, for example, what a modem is, nor the World-Wide Web, but you will need to explain what
phase modulation is, and what `CGI' stands for.
How long can the report be? It's difficult to predict in advance exactly how long a report will be, but you should be
able to decide whether you will be writing 2,000 words or 20,000 words. It's generally harder to write a short report
than a long one, because it requires much better organisation. In the university environment there may be official
limitations on the size of the report.
The first major section is an introduction; the last is a conclusion. The conclusion answers questions posed -- explicitly
or otherwise -- in the introduction.
Factual material and measurements are kept completely separate from opinion and interpretation, often in different
chapters or sections.
The report usually refers quite extensively to the work of other individuals.
Most `standard model' reports will contain some or all of the following sections, usually in this order. Each of these sections
will be discussed in more detail below.
`Abstract' or `summary'.
`Acknowledgements'.
`Introduction'.
`Objectives'.
`Theory'.
`Results'.
`Discussion' or `interpretation'.
`Conclusion'.
`Recommendations'.
2 of 9 05/03/2009 14:01
The K-Zone: How to write a technical report http://www.kevinboone.com/PF_howto_report.html
`Appendices'.
A `standard model' report will probably also contain a table of contents, a list of abbreviations and technical terms, and
perhaps an index if the document is long.
3.2 Introduction
The introduction sets out what the report is about, and what its role is in relation to other work in the field. If describing
experiments, the introduction will usually summarise other related experiments, and show how the work to be described
extends or supersedes these earlier studies. If the report is about development (e.g., software development) the introduction
will often set out what the purpose of the development is, who will benefit, and how it will be used. If the report is a review,
it will usually just state the scope of the report and the readership for which it is intended.
In most technical reports, the introduction will say something about the context of the report, that is, how the work it
describes forms part of the overall body of work in that subject area. When describing an investigation, the introduction will
usually state explicitly what the investigators set out to find.
My approach is to finish the introduction with a list of the questions I set out to answer, and give the answers to these
questions in the conclusions. I like to be quite explicit about this, and even label the questions `question 1', `question 2', etc.
Whether you do this or not, the reader should be able to look at the conclusion of your report and verify that you have found
out what you claimed you would find out.
3.3 Objectives
This section, if present, states what the work being reported was expected to achieve, why it was undertaken, and at whose
instigation. I usually prefer to put this information at the end of the introduction, but this is just a matter of taste.
3.4 Acknowledgements
It is polite to give a brief note of thanks to those people who have helped directly in the work the report describes. In a
novel, the authors often thank their friends and family; most scientists and engineers consider it slightly pretentious to do this
in a technical report. In the last few weeks I have read technical reports that acknowledged the invaluable assistance of the
late Princess of Wales, Jesus, and the author's pet dog. I would like to know in particular the role played by the dog.
If the report is destined for publication, and describes work supported by a grant, the grant-awarding body may insist that
it be acknowledged. It seems reasonable to me to do this.
3.5 Theory
The theory section, if used, describes any background theory needed for the reader to understand the report. Such a section
is usually found only in reports that use mathematics that the typical reader cannot be expected to know in advance.
3.6 Method
In the `method' section you should describe the way the work was carried out, what equipment you used, and any particular
problems that had to be overcome. If the report is describing a survey, you should say how you chose your subjects, how you
checked for bias, and how you analysed the results.
3.7 Results
In the standard model, results are usually given as plainly as possible, and without any comment. It is often difficult to know
how much data to put into this section. My feeling is that you should include enough data to enable to reader to be confident
that you have done what you said you would do, and that your conclusions will be trustworthy. This certainly does not mean
3 of 9 05/03/2009 14:01
The K-Zone: How to write a technical report http://www.kevinboone.com/PF_howto_report.html
that you should include reams of print-outs and copies of questionnaire returns. I try to summarise the results into a few
tables and graphs.
Most readers that are used to reading scientific reports will become uncomfortable if you call a section `results' and put
anything in it apart from plain results.
3.8 Discussion
In this section the author provides an interpretation of the results, compares them with other published findings -- if there are
any -- and points out any potential shortcomings in the work.
The `discussion' section of a traditional report is the place where the author is allowed to be less objective than usual. In
this section it is acceptable to mention opinions, and speculate slightly about the significance of the work.
In particular, if your findings are unusual, or very much at odds with other people's conclusions, you should explain why
you think this might be. Otherwise the reader will probably assume you have just made a mistake.
3.9 Conclusion
The conclusion gives the overall findings of the study. It is important to realise that `conclusion' does not just mean `the last
bit of the report'. Your conclusions should really be statements that can be concluded from the rest of the work. A
conclusion is not a summary. (You can include a summary as well, if you like). When I mark students' reports, one of the
questions I ask about them is `do the conclusions follow from the body of the report?'
3.10 Recommendations
In this section the author normally includes any advice he or she wishes to offer the reader. If the report is about making
some sort of business decision, the appropriate course of action will usually be recommended here. Some people use the
recommendations sections for suggestions of further work, which seems reasonable to me.
4 of 9 05/03/2009 14:01
The K-Zone: How to write a technical report http://www.kevinboone.com/PF_howto_report.html
such permission. If you don't do this you're probably breaking the law, as well as being unprofessional.
3.12 Appendices
The appendices are where the author will usually place any material that is not directly relevant to the report, and will only
be read by small number of people. I usually use appendices for mathematical proofs, electrical circuit diagrams and sections
of computer programs.
5 of 9 05/03/2009 14:01
The K-Zone: How to write a technical report http://www.kevinboone.com/PF_howto_report.html
5.2 Style
Most technical documents are written in a rather formal style. Some readers get upset when they have to read reports that
are written informally, but I don't mind this. However, what does annoy me as a reader is sudden changes from formal to
informal writing. For example, if the author adopts a impersonal, formal style (using phrases like `at this point the operator
should click on the button labelled ``start''...') and suddenly switches to an informal, personal form (`now you should click on
``start''...'), it can be very confusing.
In the UK, technical writing is usually dominated by `passive voice' expressions, where the author tries to avoid using the
word `I'. Personally, I am inclined to use the word `I' whenever I think it is appropriate to do so. If you prefer not to, that's
fine. However, you should avoid writing very ugly phrases just to avoid the word `I'. For example, a phrase commonly used
in scientific articles is `It is the opinion of the author that...' This means exactly the same as `I think...' but has four times as
many words. Lawyers tend to write `It is submitted that...' which is even worse. Submitted by whom exactly? Another error
is to use the word `we' when `I' is correct. For example, to say `we sent questionnaires to 500 middle managers' is incorrect if
it was just the author that did this (of course it is correct if there was more than one person involved). The worst affront to
the language of this type is the double passive. An example I saw recently was this: `It is regretted that transparencies are
not able to be accepted'. What the author meant was: `Sorry, we don't accept transparencies'. Authors must make up their
own minds about the good points and bad points of these different styles, but should do so after careful consideration, rather
than according to dogma.
The use of passive-voice expressions has probably derived from authors' attempts to give the impression of impartiality
when reporting scientific findings. I don't think anyone will be fooled into thinking than if you sound impartial, you are
impartial. But that's just my opinion.
In general, I think appropriate humour is fine in a technical report. The problem is this: if your report is about, say,
theorem proving methods, what sort of humour is likely to be appropriate? Many attempted jokes detract badly from the
message the author wants to convey. Nevertheless, occasionally it works.
On the whole you should probably not write the way you speak, for two reasons. First, you probably use colloquial and
ungrammatical expressions in your speech that the reader will not understand (I'm sure I do). The reader cannot stop you and
ask for an explanation. Second, in writing you don't have access to the differences in emphasis and tone of voice that help
spoken communication. As you have to rely entirely on the words themselves, you need to choose them with some care. My
favourite example of an inappropriate colloquialism occurred in the discussion section of a report I read on Web-based
learing. In doubting the validity of some statement or other, it said ``there's a great big question mark hanging over this''. In
speech this would have been fine, because the speaker's tone of voice would have indicated that he did not intend the
6 of 9 05/03/2009 14:01
The K-Zone: How to write a technical report http://www.kevinboone.com/PF_howto_report.html
statement to be taken literally. In the report however, where everything else was written in a formal way, it immediately
brought to mind an image of a flying question mark.
5.3 Presentation
Good presentation is, I venture to suggest, less important than sound technical content. However, that does not mean that it
is unimportant: the decision about how much time a potential reader is prepared to spend looking at your report will be based
to a large extent on the first impression made by the presentation.
With modern computer software, it is relatively easy to prepare well-presented documents. One area that such software
does not offer much help with is that of consistency. A document is consistent if, for example, it always uses the same
typeface for headings and for captions, if all lines have the same spacing, if all pictures are centred on the page, and so on.
The simple solution to this problem is to print the document and have it looked at by an impartial, critical person.
The final part of report preparation is usually binding. It doesn't cost very much to have a report spiral-bound, and it will
be much easier to read than if it is stapled or ring-bound. Hot glue binding can be very effective (and cheap) for thin
documents. Unless there are rules to the contrary, it is probably not worth the effort and expense of hard binding a report. I
like to receive reports that are glue-bound in plastic covers so I can read them in the bath without getting wet fingerprints on
the pages.
6 Visual material
Very few technical reports consists only of text; it is usual to include graphs, photographs, or charts as well. Here are a few
hints on including such material; these should all be quite obvious, but sometimes people forget.
Label everything. All charts and graphs should have a caption and perhaps a number (`figure 1'). Check that when you
refer to figures in the text, these references are correct. It commonly happens that people add or remove figures, then
forget to update all the cross-references.
If you prepare graphs in colour, then print them on a monochrome printer, they may become unreadable. For example,
it will not be possible to distinguish between a line that was originally back and one that was blue. Some computer
software automatically converts graphs to use dotted and dashed lines on a printer, but most does not.
Photographs do not usually photocopy very well. You may need to get extra prints made of photographs so that you
can include prints with each copy of the report.
Unlike in an advertising or promotional brochure, colour presentation is not usually worth the extra effort in a
technical document (except in certain subjects, like computer graphics and multimedia). Many scientific journals do
not print in colour, or will only do so if given a financial incentive. It's worth checking this before starting work on the
report.
Computer software that is designed for producing slide presentations will often not use sensible type sizes when used
for producing diagrams for printing on paper. A good size for text labels on a diagram is 12-14 points.
7 Things to avoid
Here, in no particular order, are some suggestions of things to avoid in a technical report. Note that I am not saying they
should be avoided in all types of writing; but a technical report has a particular function and audience, and the writing should
reflect this. Naturally this section describes things that I particularly dislike; it does not necessarily follow that everyone else
will feel the same.
Avoid clichés and stock phrases. Clichés are phrases that were probably witty and stylish when introduced, but their
very appeal has made them so over-used that they are likely to annoy the reader. Remember that the readers of
technical reports probably read a lot. They will be quite likely to have seen the same cliché used several times that
day. Here are some particularly common examples: `at the end of the day...', `explore every avenue', `not to put too
fine a point on it...', `going foward, we will...'
Stock phrases are slightly different from clichés; they are phrases that writers in a particular discipline tend to use
7 of 9 05/03/2009 14:01
The K-Zone: How to write a technical report http://www.kevinboone.com/PF_howto_report.html
too often, not because they read well, but because they get used to reading them. Particular examples include `at this
point in time...', `in the opinion of the author...' The problem with these phrases is that often they add nothing at all the
the content, or could be replaced by a single word. For example `at this point in time...' can usefully be replaced by
`now...'
Some people use stock phrases because they don't have anything else to say; if you don't have anything to say, it's
better not to say anything.
Avoid giving too much data. I suspect that some people include too much data for the same reason that some people
employ useless stock phrases: because they don't have much to say. I favour including only a summary of
experimental data in a report.
Avoid poems and other non-technical material. This sort of thing is inoffensive when it relates to the subject of the
report, but very annoying if it does not.
Avoid computer program listings and long mathematical proofs. It is unlikely that anyone will want to read them, and
anyone who does want to can ask you for a copy later.
It is probably a bad idea to include statements about how difficult the work was, and how the report would have been
better had the author had more time. Students often say this sort of thing in reports, and it doesn't look very
professional.
8 General guidelines
Finally, here are a few general suggestions, in no particular order.
Decide what you want to say, then say it. It is very difficult to think about what conclusions to draw from your
investigation, for example, at the same time as writing these conclusions. When you come to write a report, you should
be in a position to think only about reporting, not about investigation or data interpretation.
Before you write very much, check whether there are standards you are required to conform to. As a student you may
find that your place of study has quite detailed rules about report presentation. At PhD level it almost certainly will.
Some institutions specify exactly which typefaces to use for various levels of heading, and so on. For journal
publication, you'll probably find that you have to provide either `camera-ready' copy, or plain text with separate
figures. `Camera-ready' means that you should provide the finished material, ready to go to the printer. You'll have to
do all the formatting and layout yourself, according to the journal's rules. For most journals, however, you'll be
expected to provide plain text -- no layout or formatting -- and the figures on separate pages. I mention this because
there's no point spending time on getting the flow of text around your figures exactly right, when you'll end up putting
them on separate pages.
You don't have to write the report in the same order you expect it to be read. Very often the introduction is the hardest
thing to write, as you need to summarise all the work and your conclusions very thoroughly. A lot of writers start by
writing ``1. Introduction'' and then spend a few hours staring at a blank page (or blank screen). In this case you would
be better writing part of the report that is more straightforward. Often those parts of the report that deal with
methodology and procedures are quite easy to write, as no interpretation is involved.
A shorter report is a better report. If you can say the same in 2000 words as in 5000, then it's better to write 2000
words. Most people, including myself, write too much at first. By this I mean that, having written something, I can
readily remove about 20% of the words with no loss of meaning. Be ruthless: edit your work thoroughly after writing.
People find it hard to be critical of their own work. I suggest that you regard everything you write as a draft, until it
has been read by at least one other person. That other person need not be an expert in the subject, in fact it is often
better if you choose someone who is not an expert.
8 of 9 05/03/2009 14:01
The K-Zone: How to write a technical report http://www.kevinboone.com/PF_howto_report.html
Make all important style and authorship decisions before you start. Decide in advance, for example, the degree of
balance between formality and informality you will use in writing, whether you will adopt the passive or active forms,
and so on. Having made these decisions, stick to them. If you change your mind, make sure you change the whole
report. Many readers become quite uncomfortable if these major stylistic decisions change in the middle of a
document.
It's usually better not to edit your document at all until you have written the whole thing, at least to first-draft
standard. It's very easy to get bogged down with the details of individual sentences, and then find later that you need
to remove whole sections. If this happens, you will find that writing a report takes much longer than it should.
Writing good reports is difficult, and usually takes longer than the author anticipates. If possible, allow yourself twice
as much time as you first think you'll need.
Bibliography
There are many good books on the subject of technical writing, but, in my opinion, none of these are written by or for
computer scientists. The following books are the ones to which I referred when I started writing. Although they don't deal in
particular with computing, the guidance on planning, layout and style is relevant to most subjects.
Burchfield RW (1996) Fowler's modern English usage 3rd edition (Oxford: Oxford University Press)
King LS (1978) Why not say it clearly? (Boston: Little, Brown and Company)
Of these, O'Connor (1991) is probably the most accessible for beginners, but the style it advocates is a bit stuffy for my taste.
I can't be sure than any of these books (apart from Fowler's) are still in print, but in any case you should look for a book that
suits your own preference.
©1994-2006 Kevin Boone, all rights reserved
9 of 9 05/03/2009 14:01