1. 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 mark.

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.

2. 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.

3. The mechanics of writingThe 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.

4. How to write wellMany 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.

4.1. 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.

4.2. 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 Ysaid the same, only better. ``E.g.'' is overused and best used sparingly; prefer ``for instance'' or ``for example''.

4.3. 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!

4.4. 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.

4.5. 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.

5. StructureSaepe stilum vertas. - Horace 5.1. Top-level structure

At the top level, a typical report is organized in the following way.

Abstract. (This is a couple of paragraphs - no more - which summarizes the content of the report. It must be comprehensible to someone who has not read the rest of the report.)
Introduction. (The scope of the project, setting the scene for the remainder of the report.)
Previous work. (One or more review chapters, describing the research you did at the beginning of the project period.)
Several chapters describing what you have done, focusing on the novel aspects of your own work.
Further work. (A chapter describing possible ways in which your work could be continued or developed. Be imaginative but realistic.)
Conclusions. (This is similar to the abstract. The difference is that you should assume here that the reader of the conclusions has read the rest of the report.)
References and appendices.

5.2. References

References must be relevant. A typical PR3 project report might contain about one page of pertinent references, if the initial research period was well spent. Do not include references which you have not read, no matter how relevant you think they might be. If you refer to standard material which is covered by a large number of text-books, choose one or two really good ones and cite those, rather than a long list of mediocre texts.

There are many styles for citing references. Although strict standards (e.g. British Standards) for citing references exist, my advice is not to bother with them; instead, find a reputable journal in the library and copy its style. Alternatively, copy the example below. It's important to be consistent, complete and unambiguous; beyond that, it doesn't matter much what you do.

Example citation style:

Citations in text: Mander, in ``Notes on a system specification method'' [Mander 1983], gives the following ...

... as described by Briggs [1983a] ...

Thimbleby's guidelines [Thimbleby 1983] suggest that ...

Different methodologies have been examined [Tully 1983].

Several recent publications in this field [Wand 1980d, ACM 1971] have been very influential.

List of references at end of report:ReferencesACM 1971.Association for Computing Machinery, Second symposium on problems in the optimisation of data communication systems, ACM (1971).Briggs 1983a.J.S. Briggs, ``The design of AIR and its use in Ada separate compilation'', in SERC workshop on Ada software tools interfaces, ed. P.J. Wallis, University of Bath (1983).Downes 1982.V.A. Downes, S.J. Goldsack, Programming embedded systems with Ada, Prentice-Hall (1982).Mander 1983.K.C. Mander, Notes on a system specification method, York Computer Science report no. 61, University of York (1983).Thimbleby 1983.H.W. Thimbleby, ``Guidelines for `manipulative' text editing'', Behaviour and Information Technology, 2, 127 - 161 (1983).

If you adopt this style, when you cite a reference, you need not repeat the author's name or authors' names (``Jones and Sanderson [Jones & Sanderson 1999] have shown ...''). Write instead: ``Jones and Sanderson [1999] have shown ...'', and list the reference as ``Jones & Sanderson 1999''.

Alternatively, a system of numbered references, such as the default format produced by the Unix refer tool in conjunction with troff, is acceptable. I myself much prefer numbered citation styles, which I find much less obtrusive and easier on the eye; e.g. ``Jones and Sanderson¹ have shown ...'' or ``Jones and Sanderson [1] have shown ...''. These forms, which are allowed by the regulations in the Handbook, seem to be the two dominant citation styles in academic journals.

You may wish to refer to electronic sources, particularly material found on the World-Wide Web. It is not enough to put ``found on WWW'' in place of a citation. The web page ``Bibliographic Formats for Citing Electronic Information'' gives advice on citing on-line sources.

If possible, avoid citing unpublished literature. It is however acceptable to cite university reports, such as this Department's YCS series, and PhD theses (although getting hold of the latter can be almost impossible).

``References'' are always cited in the text. Other works you've made use of but not cited should be listed in a section called ``Bibliography''.

Note that ``et al.'' requires a period after the abbreviation ``al.'' (for ``alia''). It means ``and others'', and may be used only to refer to people, typically in lists of references. It is the animate form of ``etc.'', which also requires a period.

5.3. Lower-level structure

Structure is a recursive concept. A well-structured report has its top-level sections well ordered, and it is easy to get this right; but each section must in itself be well ordered, and that is more difficult.

Most paper documents, and many on-line documents, are read linearly from beginning to end. This is certainly true of an examiner reading a project report. Consequently, the writer of a well-structured document avoids forward references wherever possible. Try to avoid writing ``... as we shall see in chapter 10, ...'', especially if the material in chapter 10 is essential to an understanding of the text at the point where the reference occurs. Occasionally such references are unavoidable, but more often than not they are a sign that the text needs to be re-ordered.

In the old days, re-ordering text entailed ``cutting and pasting'' with real scissors and real paste. Nowadays, the word-processor has made these operations so easy that there is no excuse for slovenly structure. Take your time, and keep rearranging words or phrases within sentences, sentences within paragraphs, paragraphs within sections and sections within the whole report until you have got it right. Aim for a logical progression from beginning to end, with each sentence building on the previous ones.

If the chapters are numbered 1, 2, 3, ..., then the sections within (say) chapter 1 will be numbered 1.1, 1.2, ... . It is permissible to sub-divide a section: the sub-sections within section 1.1 will be numbered 1.1.1, 1.1.2, ... . Do not however nest sub-sections to more than four levels: sub-sub-section 1.2.3.4 is acceptable, but 1.2.3.4.5 is not. It is quite possible, with care, to write even a large and complex book without using more than three levels.

Footnotes are a nuisance to the reader. They interrupt the linear flow of text and necessitate a mental stack-pushing and stack-popping which demand conscious effort. There are rare occasions when footnotes are acceptable, but they are so rare that it is best to avoid them altogether. To remove a footnote, first try putting it in-line, surrounded by parentheses. It is likely that the poor structure which was disguised by the footnote apparatus will then become apparent, and can be improved by cutting and pasting.

6. The role of artefacts in projectsDeep down, all students seem to believe that their project is ``to write a program'' (or, ``to build a circuit''). They believe that they will be judged by how much their program does. They are amazed when their supervisor is unconcerned about the inclusion or non-inclusion of a listing in the report. They fear that they will be penalized if their program is small-scale or if they do not make grandiose claims for its power and functionality.

This leads to reports heavy with code and assertions about code, but light on reasoning. Students omit the reasoning because they are short of time and think the code more important, and thereby they lose credit they could have had. It leads also to the omission of testing. Hence there are assertions about the extent of implementation, but no evidence (in the form of records of testing) to back them up.

In summary, credit for the implementation is not the whole story; you should not feel under pressure to make claims that you cannot support. Your reports should clearly separate specification, design, implementation and testing. ``The program does X'' should more honestly be ``I wanted the program to do X; I designed it to do nearly-X; I implemented it to do most-of-X; my testing shows that it did some-of-X(and here is the evidence of that)''. Taking this advice into account can much improve your mark.

7. You and your supervisorWriting is a solitary pursuit. Whereas your supervisor will guide you through the early stages of your project work, you must write the report on your own. It is a University assessment, and the rules on plagiarism and collusion (do consult the Students' Handbook!), and the conventions which restrict the amount of help a supervisor can give, apply. Nevertheless, most supervisors will be happy to read and to comment on drafts of sections of your project report before you hand it in, if you give them enough time to do so. It's also a good idea to ask your supervisor to suggest some high-quality past projects in a similar field to yours, and to look them up in the departmental library. This will give you an idea of what is required. 8. Summary

Good writing is difficult, but it is worth taking the trouble to write well.
Leonard was trying to form his style on Ruskin: he understood him to be the greatest master of English prose. He read forward steadily, occasionally making a few notes.
``Let us consider a little each of these characters in succession, and first (for of the shafts enough has been said already), what is very peculiar to this church - its luminousness.'' Was there anything to be learnt from this fine sentence? Could he adapt it to the needs of daily life? Could he introduce it, with modifications, when he next wrote a letter to his brother, the lay reader? For example: ``Let us consider a little each of these characters in succession, and first (for of the absence of ventilation enough has been said already), what is very peculiar to this flat - its obscurity.'' Something told him that the modifications would not do; and that something, had he known it, was the spirit of English Prose. ``My flat is dark as well as stuffy.'' Those were the words for him.

Resources

Top Categories

Product

Company