University of York, Department of Computer Science How to Write a Project Report 1. Why is the report important?

If you wish to secure a good mark for your project, it is absolutely essential t hat you write a good report. It is the report which is marked, not the program o r anything else you might have constructed during the project period. No matte r 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 numbe r 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 i n the report. 2. What are the examiners looking for?

Each project report is marked initially by two examiners, one of whom is the sup ervisor. Each examiner fills in an online mark form, giving marks for various as pects 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 particula r numerical mark (e.g. 5 is ``satisfactory''). There is a separate document whic h goes into great detail about what precisely ``satisfactory'' means in particul ar contexts, but I'm not sure that these definitions are widely used: most exami ners 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 o f the project is to be assessed - for example, a review of the project area - ev en 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 st andard headings, think carefully about what you present (or do not present) unde r 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 princ iples, pose and answer questions, measure success, analyse alternatives and so o n. 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 suppor ting industry, should be discussed. 3. The mechanics of writing

The problem you have to solve is this: to transfer your own experiences of doin g 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 techn iques. My own method, which I think is quite common among technical authors, i s 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 w hich 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 wh ere I was. The aim is to transfer as much relevant material from brain to p aper 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 au thors. After three hours of ``brain dumping'' I might have four or five pages of disorg anized text. I then spend perhaps six hours putting the text into order and tigh tening 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 illu strations. Good-quality illustrations, in particular, take a long time to prepar e. 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 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 Barra ss (1982). Though published over twenty years ago, this superb little book is st ill 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 suffic ient that you know what you mean; neither is it sufficient that your writing adm its 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, prov ided that the short word has the meaning you need. Terseness is a great virtue i n technical writing. (But don't go too far; remember Horace's observation: ``Bre vis esse laboro, obscurus fio''.) Avoid circumlocutions. ``In almost all sectors of the computing marketplace'' can be replaced in most contexts by ``alm ost everywhere''. The question of whether to use the passive voice in technical writing is a thorn y one. Most older writers still write ``a program was written ...'' rather than ``I wrote a program ...''. Many of your examiners might share this preference f or, 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 writ ing (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 a bbreviates a circumlocutionary English phrase. Mutatis mutandis, for example, on e of my own favourites, is permissible in place of ``making the appropriate chan ges'', 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 b e 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 i nstance'' or ``for example''. 4.3. Spelling and grammar

You must take exceptional care to spell correctly. Poor spelling is a distractio n to the proficient reader. In most cases there is very little excuse nowadays f or spelling errors; there are many excellent spell-checker programs which make a good job of finding the errors for you, and excellent (paper) dictionaries whic h 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 particul ar 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 hilari ous ``corrections'' have been reported, for example recently in New Scientist. Believe the spell-checker. Very many people, for example, on finding that the sp ell-checker questions ``idiosyncracy'' [sic], say to themselves ``it must be mis sing from the dictionary file'', and leave the word alone. It is - for a good re ason. If you have a medical condition which makes it difficult for you to spell correc tly, 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 m ore so. There are so many potential grammatical solecisms that it would be inapp ropriate to attempt to list them here. Read Fowler's Modern English Usage for gu idance. 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 it s recommendations are more permissive or up-to-date, but because it draws attent ion to traps which it would not have occurred to Fowler in 1926 that anyone coul d fall into. The original 1926 edition is famous for its vigorous, fiery languag e, 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 reas on, careful writers of British English restrict the possessive use of the apostr ophe to animate possessors. You may write ``John's book'' but not ``the pro gram's function'', since (so the argument goes) one cannot write ``the program h is function'': you must write ``the function of the program'' instead. This rule is being steadily eroded under American influence, and will probably soon be ob solete. 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-leve

l macro-expansion, replacing ``it's'' by ``it is''. This then fails to make syntactic sense in the context, necessitating a backtracking and re-parsing oper ation, and conscious expenditure of effort. It really does slow down, and c onsequently annoy, the reader. This crass and ignorant blunder probably does mor e to distract and to impede the reader of students' reports than any other gramm atical solecism. Summary: ``it's'' = ``it is'' (needed rarely, if at all, in formal writing). ``I ts'' is the pronoun (This is my program. Its purpose is to ... .) You almo st certainly mean ``its''. Even if you yourself do not place a strong emphasis on good spelling and good gr ammar, most of your examiners do, some fanatically. Most examiners will be irrit ated by poor spelling and poor grammar. It is always worth doing whatever you ca n, short of bribery, to put your examiner in a good mood. Write well and spell w ell, 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 an d 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 responsib le for producing a computer-typeset report. This means that you must be familiar both with the formal requirements set out in the Students' Handbook (restrictin g the number of pages, type size, width of margins, and so on) and with the rudi ments of typography. You will not be penalized severely, if at all, if you viola te typographical conventions, but good typography creates a subliminal impressio n akin to that of good proportion in a painting, and is desirable for that reaso n. Since it is a matter of simply learning and following the rules, you should t ry to do so. You should learn at least enough (for example) to know the differen ce 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 a nd readers at the University Press, Oxford by Horace Hart, known colloquially an d 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 t he O.U.P. since 1893). The latest edition is dated 1983. It is still in print, a lmost a century after its first publication, and at 8.79 (from the Internet Books hop), well worth buying. 4.5. Illustrations

Your report should generally contain illustrations (figures or diagrams), but th ey must be relevant. Ask yourself if the illustration helps the reader to unders tand the text. If the text is readily comprehensible without the illustration, d elete the illustration. If it is not, it is usually better to make the text clea rer than to add a diagram. All illustrations should be prepared by an appropriate program, such as pic, xfi g or grap. They should not be hand-drawn. The only common exception to thi s rule is circuit diagrams: given the current state of the art in schematic-entr y packages, a hand-drawn circuit diagram is usually preferable to a computer-dra wn 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 re port, after the table of contents. 5. Structure

Saepe stilum vertas. 5.1.

- Horace

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 conte nt 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 co ntinued or developed. Be imaginative but realistic.) Conclusions. (This is similar to the abstract. The difference is that you shou ld assume here that the reader of the conclusions has read the rest of the repor t.) References and appendices. 5.2. References References must be relevant. A typical PR3 project report might contain about on e 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 th ink 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. Bri tish Standards) for citing references exist, my advice is not to bother with the m; instead, find a reputable journal in the library and copy its style. Alternat ively, copy the example below. It's important to be consistent, complete and una mbiguous; 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 f ollowing ... ... 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: References ACM 1971. Association for Computing Machinery, Second symposium on proble ms in the optimisation of data communication systems, ACM (1971). Briggs 1983a. J.S. Briggs, ``The design of AIR and its use in Ada separate co mpilation'', 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 A da, Prentice-Hall (1982).

Mander 1983. K.C. Mander, Notes on a system specification method, York Compu ter 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 auth or'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 produ ced 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 easi er on the eye; e.g. ``Jones and Sanderson have shown ...'' or ``Jones and Sanders on [1] have shown ...''. These forms, which are allowed by the regulations in th e 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 ci te university reports, such as this Department's YCS series, and PhD theses (alt hough 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 ``ali a''). It means ``and others'', and may be used only to refer to people, typicall y in lists of references. It is the animate form of ``etc.'', which also require s a period. 5.3. Lower-level structure

Structure is a recursive concept. A well-structured report has its top-level sec tions well ordered, and it is easy to get this right; but each section must in i tself be well ordered, and that is more difficult. Most paper documents, and many on-line documents, are read linearly from beginni ng to end. This is certainly true of an examiner reading a project report. Conse quently, the writer of a well-structured document avoids forward references wher ever 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 r e-ordered. In the old days, re-ordering text entailed ``cutting and pasting'' with real sci ssors 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 re arranging words or phrases within sentences, sentences within paragraphs, paragr aphs 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 b uilding on the previous ones. If the chapters are numbered 1, 2, 3, ..., then the sections within (say) chapte r 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 a cceptable, 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 struct ure 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 projects

Deep down, all students seem to believe that their project is ``to write a progr am'' (or, ``to build a circuit''). They believe that they will be judged b y how much their program does. They are amazed when their supervisor is unconcer ned about the inclusion or non-inclusion of a listing in the report. They fear t hat they will be penalized if their program is small-scale or if they do not mak e grandiose claims for its power and functionality. This leads to reports heavy with code and assertions about code, but light on re asoning. Students omit the reasoning because they are short of time and think th e code more important, and thereby they lose credit they could have had. It lead s also to the omission of testing. Hence there are assertions about the extent o f implementation, but no evidence (in the form of records of testing) to back th em 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 progr am does X'' should more honestly be ``I wanted the program to do X; I designed i t 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 supervisor

Writing is a solitary pursuit. Whereas your supervisor will guide you through t he 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 consul t the Students' Handbook!), and the conventions which restrict the amount of hel p 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 you rs, 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 gre atest 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 (fo r of the shafts enough has been said already), what is very peculiar to this chu rch - its luminousness.'' Was there anything to be learnt from this fine sentenc e? Could he adapt it to the needs of daily life? Could he introduce it, with mod ifications, when he next wrote a letter to his brother, the lay reader? For exam ple: ``Let us consider a little each of these characters in succession, and firs t (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 modificati ons 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.) Written by Dr A.J. Fisher. James Cussens / Projects Coordinator / [email protected]. uk