Alistair D N Edwards
These notes are provided with the aim of helping you to write a better report and of stopping you from throwing away marks unnecessarily. As well as these notes, you would be well advised to also carefully read the section on projects in the Student Handbook and to read the web pages on How to Write up a Project.
No one can tell you how to write or dictate your style, but there are certain mistakes which students often make simply because they are unused to writing scientific papers. Of course, markers are just as variable as writers, and these guidelines display my own biases, which may be different from other people's. There is a safeguard, however, in that all projects are marked by at least two people - who all mark according to a standard format. The format is based upon the following aspects of the report:
There are page and word limits on reports. See youe Student Handbook for details. There is no minimum length. However, you should be aware that a very short report is unlikely to have sufficient content to be worthy of a good mark.
These limits may seem quite short. That is deliberate and should encourage you to achieve an economic, concise use of language. Please refer carefully to the Student Handbook for details of these and other constraints on project reports. Failure to do so can cause serious problems.
This is the topic on which probably least advice can be given. Writing clearly is something you can either do - or you have to work at. Any book on technical writing or style will help, but you might like to refer to the recommended text for the (former) Use of English course [Turk and Kirkham, 1982]. You may also refer to the document Writing for Humans.
Presentation is important. A report which is well laid out is easier to read and immediately predisposes the marker positively. It is departmental policy that students are expected to produce documents using a word or text processor, handwritten texts are allowed only in exceptional circumstances. Whatever medium you use, the presentation must be clear and easily readable. One advantage of word processing is that you have the opportunity to spell check your work, and there is really no excuse for silly spelling errors in a word processed document. However you produce your report, you must proof read it. Even good spelling checkers do not catch many easily made errors. In fact it is best to get someone else to proof read it, if possible. Generally writers are so familiar with their own documents that they can easily skip over errors.
Your project report is a scientific paper, so there are certain aspects of style which are expected. Making it readable is one thing, but writing it in the style of a novel or tabloid newspaper is not acceptable. For instance, one-sentence - or even one-word - paragraphs are not acceptable. Computer Science abounds with three-letter acronyms (TLAs) and they should always be written out in full the first time you use them - even those in common usage.
The essence of good writing is to know your reader. In most writing this can be hard as the audience may be very ill-defined, but in the case of a project report, you generally have a clear idea of your readership. The report should be understandable and readable for someone with a good background in Computer Science. Do not think specifically of writing for your supervisor, who has additional background in your topic area, but more for the second marker, who knows about Computer Science in general, but may never have even thought much about your particular topic. Of course, there may be exceptions. If your project includes a user manual, that may have to be written for a less-well-informed reader, or if your topic veers from straight Computer Science (into Psychology, for instance) you may have to provide more background.
Do not simply provide a description of your program. This is boring and unnecessary. If readers really want to know about this, they will be quite capable of reading the code. If necessary, you might provide a high-level description of the structure and/or operation of the program, but beware of any more detail than that.
You must acknowledge the use of any software not written by you (e.g. library routines). You may want to use direct quotes from other people's work, but do not over do it. (See below on plagiarism). A quote should be used if:
Only in exceptional circumstances should you express an opinion. At all other times you must be able to back up what you write. You do that either by presenting the results of your work or by making reference to the literature. It is important that the reader should be able to see exactly where they should go to get further information on any topic you bring up. If you should express an opinion, it should be clearly marked as such, in such a way that it cannot be confused with demonstrable facts.
Use diagrams, figures and tables where appropriate. A picture may be worth one thousand words - if it is a good one. You must refer to any figures and tables in the body of the text, (e.g. 'as shown in Figure 3...'), to give the reader an indication of when would be a good time to look at it. All figures and tables should also be accompanied by a caption. The text and the figure should be to some degree independent. In other words, it should be possible to (largely) understand the figure with the aid of its caption, without having to read the corresponding section of the text.
The Abstract should capture the essence of your report. Its purpose should be to enable a reader to decide whether the full report will be of interest to them. Everything important that you have done, discovered and concluded should be mentioned, but briefly and concisely. Some students seem to get confused as to whether they are writing a 'whodunnit', and they want to make the reader get all the way to the final section before they reveal their results and conclusions, whereas all the major ones should be mentioned in the Abstract.
The abstract and the report should be capable of being read independently. In other words, in writing the report do not assume that the reader has already read the abstract - and vice versa. It is allowable (indeed, necessary) to repeat yourself. So, do not treat the abstract as part of the introduction.
Compiling the Contents list is a fairly simple task - especially if you are using a work processor which will do it for you. It should provide a 'map' to help guide the reader through the document.
Although the mark sheet mentions an Index, it seems unlikely that all students can be expected to provide one. Obviously, if your word processor will build one for you, then use that facility.
You must show how your work fits in with what has gone before. Your project will generally fall into one of two types: research or development. A development project will generally involve implementing something which has been done before. For instance, writing a new Ada compiler would be a development project, because Ada compilers already exist. You start off knowing it can be done, and could succeed by simply using techniques already proven. A research project involves attempting something novel, which has not been done before. You will be trying something which may or may not work.
In some ways the review for a research-style project is easier. You will have to fill in the background of previous work which got you to the stage where you were able to start your project as well as possibly inspiring the project in that a gap or development was identified. However the review in a development project is no less important (it carries the same marks) but you may structure it more in terms of explaining design decisions. You will have to show how you examined a number of alternative approaches to different aspects of the project (which are described in the literature) and why you chose to go the direction in which you went.
You must cite all sources of information. You should make it clear what has been derived from your experiments and what you have learned from the literature. To not cite references might be construed as plagiarism. Plagiarism is against University regulations and could result in you failing your degree, so take great care that you do not write anything which could even be mis-construed as plagiarism. Consult the Student Handbook for guidance on the regulations and on the expected format of references. It is important that you should get the format right and that you should give complete information; it is your responsibility to ensure that a reader could follow up any reference. Marks will be deducted for bad references.
What goes into this section very much depends on the nature of your project. It is assumed that a project involves the production of some artefact (though the possibilities as to what that is are broad - it need not necessarily be a piece of hardware or software). You must have designed it and the rationale behind that design must be explained. Design is always a matter of compromise and you should make it clear which options you considered and why the benefits of the options you chose outweighed their disadvantages.
Your concluding section must summarize what you have done and what conclusions you can draw. You must not introduce new material, but draw out the lessons from the material in the preceding sections.
Be self-critical. As the coach of an Australian rugby team once said, 'Get your retaliation in first.' If you try to hide the deficiencies of your project, you may not succeed, and you will then lay yourself open to criticism, whereas if you are open about them you will probably get credit for your analytical approach.
An important sub-section is usually 'Future Work'. Show how your achievements might be built on - possibly as future students projects, or even as research work.
One of the most annoying errors I find when marking projects is inconsistent and incorrect use of the apostrophe. The apostrophe is used mainly for two purposes:
In general the former use of the apostrophe is inappropriate in a technical paper; the full word should be used instead. In other words you should not write things such as shouldn't or can't but should not and cannot The only exception might be when you are quoting speech. For instance, if you have transcribed the dialogue of a test subject you might accurately report the manner of their speech.
The second use may occur, for instance I recorded the user's opinions. A complication occurs when the noun already ends in an s - either because that is the last letter or because the word is plural. In that case the apostrophe is usually placed after the s. For instance, if there were more than one users, then you might write that I recorded the users' opinions. The different position of the apostrophe is subtle, but clearly the meaning is very different.
There is a further complication with the word it. From what has been said above about possessives you might conclude that referring to something owned by an inanimate object you would write it's, but you would be wrong. It's means it is. This may appear inconsistent and irregular, but if you think about it, it is consistent with her and hers, their and theirs etc. When proof reading anything you have written, if you come across an occurrence of it's then read it as it is and see if it makes sense (and if you are writing a technical document, such as a project report, you should probably not have used a contraction such as it's anyway).
When studying English it's clear that its rules are not always consistent.
There is a school of thought that says that numbers should have apostrophes, as in
If you can remember the 1960's you can't have been there.
I cannot see any reason for it though, and I would simply write 1960s.
You will find more on this topic in [Fowler, 1926] under it and Possessive puzzles and if these explanations are not clear, executing the following program in your head may help you get it right. The variable word refers to the word you are dealing with and the '+' operator implies concatenating the operands (e.g. house + s = houses).
if plural(word)
then
if possessive(word)
then
if lastchar(word) = s
then word := word + '
else word := word + s'
else word := word + s
else
if word = it is
then word := it's
else
if possessive(word)
then
if word = it
then word := its
else
if lastchar(word) = s
then word := word + '
else word := word + 'sPlagiarism is an offence against university regulations. A degree can be withheld if plagiarism is detected. Do not even think of trying it. By all means use other people's work - but acknowledge the source. Read the Student Handbook carefully on this topic.
Department of Computer Science Home Page
Alistair Edwards (alistair@cs.york.ac.uk)
30/8/12