WHY IS THE REPORT IMPORTANT?
If you wish to secure a good mark for your project, it is absolutely
essential that you write a good report. It is the report which is
marked, not the program or anything else you might have constructed
during the project period. No matter how significant your achievements,
if you do not write up your work, and write it up well, you will obtain a
poor market.
It is essential to understand that the report will be read and marked by a number of examiners (normally 2 – 4), only one of whom – your supervisor – will have any familiarity with the work which the report describes. Examiners are not mind-readers, and cannot give credit for work which you have done but not included in the report.
WHAT ARE THE EXAMINERS LOOKING FOR?
Each
project report is marked initially by two examiners, one of whom is the
supervisor. Each examiner fills in an online mark form, giving marks for
various aspects of the report and an overall mark. Studying the mark sheet will
give you a good idea of what aspects of the report are important.
The
notes to examiners which accompany the mark sheet use the terms “perfect”,
“quite good”, “abysmal” and so on to describe the attributes of a particular
numerical mark (e.g. 5 is “satisfactory”). There is a separate document which
goes into great detail about what precisely “satisfactory” means in particular
contexts, but I’m not sure that these definitions are widely used: most
examiners believe that they have an accurate and objective understanding of
what is “satisfactory”.
Note
that supervisors might specify on the mark sheet that a particular aspect of
the project is to be assessed – for example, a review of the project area –
even if that area is not covered in the project report. Decisions on what is to
be assessed are the supervisor’s responsibility, but you should be aware of the
standard headings, think carefully about what you present (or do not present)
under each, and discuss and agree it with your supervisor.
Remember
that your report is an academic dissertation, not a popular article or
commercial proposal. For example, rather than describing only a series of
events and a final product, try to establish criteria, present arguments,
derive principles, pose and answer questions, measure success, analyse
alternatives and so on. Where a project has been undertaken with industrial
support, the significance of that support for the project, and the relevance of
the project to the supporting industry, should be discussed.
THE MECHANICS OF WRITING
The
problem you have to solve is this: to transfer your own experiences of doing
the project, and the knowledge you have gained, from your brain onto paper in a
coherent, logical and correct form.
There
are several ways of achieving this. Different authors have different
techniques. My own method, which I think is quite common among technical
authors, is to write as quickly as I can, without regard for coherency,
structure or order, until I have written down (or rather, typed in) all the
points I can think of. If my brain is running faster than my fingers and a
thought pops into my head which belongs in another part of the document, I skip
to the end of the page and insert a few words there to remind me to expand that
point later, then resume where I was. The aim is to transfer as much relevant
material from brain to paper as quickly as possible. This method has been
called the “brain dump”. It is practised, I think, by some writers of fiction
as well as by technical authors.
After
three hours of “brain dumping” I might have four or five pages of disorganized
text. I then spend perhaps six hours putting the text into order and tightening
up the prose, after which I might have three pages of good-quality prose. This
method of writing is an iterative process, with periods of “brain dumping”
alternating with periods of tidying-up.
At
the rate of three pages of polished text every nine hours, a typical 60-page
PR3 project report will take you about four weeks to complete, working
full-time. You must allow time to prepare the appendices (e.g. program
listings) and illustrations. Good-quality illustrations, in particular, take a
long time to prepare. You should therefore allow at least six weeks to write
the report.
If
you kept a note-book during the project period, you will find the writing-up
process much easier.
HOW TO WRITE WELL
Many
students appear not to realize how difficult it is to write well. Any type of
writing (except perhaps advertising copy) is difficult, but technical writing
is particularly hard.
There
are many books which
address the subject of good technical writing. By far the
best among those which I have seen is Scientists Must Write by Robert Barrass
(1982). Though published over twenty years ago, this superb little book is
still in print. There are several copies in the J.B. Morrell library, but since
it costs only £11.19 (from the Internet Bookshop), you would be well advised to
buy a copy and to read it from cover to cover.
PRECISION
You
must strive first to be absolutely precise. When you write, it is not
sufficient that you know what you mean; neither is it sufficient that your
writing admits of the meaning which you intend: it must admit of no other
meaning. What you write must not be capable of misinterpretation. Take
exceptional care to choose the right word for the occasion. Do not, for
example, write “optimum” if you mean “good”. “Approximate” means “close”, so
“very approximate” means “very close” – which is not what many people seem to
think it means.
VIGOUR
Precision
in writing is mainly a matter of taking sufficient care. Good writing is not
only precise, however, it is vigorous, and that is much harder to achieve. It
helps if you have read widely, especially novels. Here are some hints which
might help you to write forcefully and vigorously.
Prefer
short sentences to long sentences. Prefer short words to long words, provided
that the short word has the meaning you need. Terseness is a great virtue in
technical writing. (But don’t go too far; remember Horace’s observation:
“Brevis esse laboro, obscurus fio”.) Avoid circumlocutions. “In almost all
sectors of the computing marketplace” can be replaced in most contexts by
“almost everywhere”.
The
question of whether to use the passive voice in technical writing is a thorny
one. Most older writers still write “a program was written …” rather than “I
wrote a program …”. Many of your examiners might share this preference for, or
prejudice in favour of, the passive voice, but this style is passing out of
favour in all technical writing, and I advise you not to use it. Whatever you
do, do not use the “royal we” (“we wrote a program” when you mean “I wrote a
program”).
There
is general agreement that Latin phrases are best avoided in technical writing
(but the occasional Latin quotation might lend a spurious air of erudition!)
Nevertheless, many careful writers have their own favourite Latin phrases which
find occasional use. The best rule is that a Latin phrase is acceptable if it
abbreviates a circumlocutionary English phrase. Mutatis mutandis, for example,
one of my own favourites, is permissible in place of “making the appropriate
changes”, since any English gloss seems to be ugly and unwieldy. “I.e.” (note
the roman font and punctuation) is often useful in place of “in other words” or
“that is”, and is widely understood. Quite often, however, “X, i.e., Y” can be
replaced by “Y”, because the writer realized while writing X that Y said the
same, only better. “E.g.” is overused and best used sparingly; prefer “for
instance” or “for example”.
SPELLING AND GRAMMAR
You
must take exceptional care to spell correctly. Poor spelling is a distraction
to the proficient reader. In most cases there is very little excuse nowadays
for spelling errors; there are many excellent spell-checker programs which make
a good job of finding the errors for you, and excellent (paper) dictionaries
which will tell you what the correct spelling is. Be especially careful with
words whose common misspelling is a correct spelling of a different word, in
particular the following pairs: lead/led; loose/lose; affect/effect. It is
dangerous to allow the spell-checker to “correct” a misspelling by itself; many
such hilarious “corrections” have been reported, for example recently in New
Scientist.
Believe
the spell-checker. Very many people, for example, on finding that the
spell-checker questions “idiosyncracy” [sic], say to themselves “it must be
missing from the dictionary file”, and leave the word alone. It is – for a good
reason.
If
you have a medical condition which makes it difficult for you to spell
correctly, make sure that your supervisor knows about it, so that it can be
taken into account by the examiners.
If
poor spelling is a distraction which impedes understanding, poor grammar is
more so. There are so many potential grammatical solecisms that it would be
inappropriate to attempt to list them here. Read Fowler’s Modern English Usage
for guidance. This book has been revised several times since its first
publication in 1926. The most recent (1998) edition is probably the best to use,
not because its recommendations are more permissive or up-to-date, but because
it draws attention to traps which it would not have occurred to Fowler in 1926
that anyone could fall into. The original 1926 edition is famous for its
vigorous, fiery language, which has been successively watered down in later
revisions.
Take
care with apostrophes. Historically, the apostrophe denoted the omission of one
or more letters: don’t = do not, John’s book = John his book. For this reason,
careful writers of British English restrict the possessive use of the
apostrophe to animate possessors. You may write “John’s book” but not “the
program’s function”, since (so the argument goes) one cannot write “the program
his function”: you must write “the function of the program” instead. This rule
is being steadily eroded under American influence, and will probably soon be
obsolete.
I
mention the “animate possessor” rule in order to illustrate and to explain a
very common blunder. Never use an apostrophe with a possessive pronoun. “It’s”
means “it is” (the letter that’s omitted is an “i”), not “it his”, which is
plain silly. One never sees spurious apostrophes in his, hers, ours, yours,
theirs; so why does one so often see “it’s” in place of “its”, which is the
correct possessive pronoun?
The
brain of the experienced reader, on seeing “it’s”, performs a lexical-level
macro-expansion, replacing “it’s” by “it is”. This then fails to make syntactic
sense in the context, necessitating a backtracking and re-parsing operation,
and conscious expenditure of effort. It really does slow down, and consequently
annoy, the reader. This crass and ignorant blunder probably does more to
distract and to impede the reader of students’ reports than any other
grammatical solecism.
Summary:
“it’s” = “it is” (needed rarely, if at all, in formal writing). “Its” is the
pronoun (This is my program. Its purpose is to … .) You almost certainly mean
“its”.
Even
if you yourself do not place a strong emphasis on good spelling and good
grammar, most of your examiners do, some fanatically. Most examiners will be
irritated by poor spelling and poor grammar. It is always worth doing whatever
you can, short of bribery, to put your examiner in a good mood. Write well and
spell well, for this reason if for no other!
TYPOGRAPHY
When
I prepared my own final-year project report, I wrote it with pen and ink and
handed the manuscript to the departmental secretary who typed it for me on an
IBM typewriter. Modern practice is different, and now you yourself are
responsible for producing a computer-typeset report. This means that you must
be familiar both with the formal requirements set out in the Students’ Handbook
(restricting the number of pages, type size, width of margins, and so on) and
with the rudiments of typography. You will not be penalized severely, if at
all, if you violate typographical conventions, but good typography creates a
subliminal impression akin to that of good proportion in a painting, and is
desirable for that reason. Since it is a matter of simply learning and
following the rules, you should try to do so. You should learn at least enough
(for example) to know the difference between the hyphen, minus, en-dash and
em-dash, and when to use each of them.
The
best and most famous typographical reference book is Rules for compositors and
readers at the University Press, Oxford by Horace Hart, known colloquially and
universally as “Hart’s Rules”. It is a small book which you should probably
read from cover to cover, but you may skip the section on Russian orthography
if your report contains no Russian words. This book, like Fowler, has been
revised continually since its first publication (in 1904, though it was in use
within the O.U.P. since 1893). The latest edition is dated 1983. It is still in
print, almost a century after its first publication, and at £8.79 (from the
Internet Bookshop), well worth buying.
ILLUSTRATIONS
Your
report should generally contain illustrations (figures or diagrams), but they
must be relevant. Ask yourself if the illustration helps the reader to
understand the text. If the text is readily comprehensible without the
illustration, delete the illustration. If it is not, it is usually better to
make the text clearer than to add a diagram.
All
illustrations should be prepared by an appropriate program, such as pic, xfig
or grap. They should not be hand-drawn. The only common exception to this rule
is circuit diagrams: given the current state of the art in schematic-entry
packages, a hand-drawn circuit diagram is usually preferable to a computer-drawn
one.
If
possible, include figures close to the text which refers to them, rather than
all together in an appendix. Circuit diagrams are, again, a possible exception
to this rule. It is normal to list tables and figures at the beginning of the
report, after the table of contents.