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.
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.
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.
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.
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''.
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!
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.
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.
Saepe stilum vertas. - Horace
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.
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:
| ||||||||||||
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.
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.
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.
``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.
E.M. Forster, Howard's End
(quoted in Barrass, op. cit.)