Ken Brown's Guide to 4th Year Projects

All,

some notes on the project process, and on what is expected for the final report.

Ken Brown


1. We must get a project plan agreed early in the project period - at least by mid October. The plan should include a brief motivation for the project, a high-level description of what you are going to produce and what "science", if any, is in the project. It should state any papers, published work or available software on which the project is based, or which were the inspiration for the project. It should list any essential hardware, software or network access needed to complete the project. It should then have a list of subtasks / subgoals, with a description of each, and a timeline or gantt chart showing when you expect each subtask to be complete. You should describe what subtasks are essential to a successful project, what other ones you intend to achieve, and a list of extra ones that you would do if everything goes faster than expected. You should make sure that you are not leaving everything to come together in the last week - instead, your timeline should have the essential tasks complete by the end of January, which will give you some slack in case something goes wrong and will leave you time to bundle up what you have as a coherent project. You should do some risk assessment - what could go wrong, and what will you do if it does. Make sure you leave enough time in your workplan to conduct whatever experiments you are going do, and to write up the report - remember that the 2nd marker, the external examiner, any marks calibration committee, and the department exam board will only see your written report, and so most of the marks are dependent on the write-up.

When we are marking the projects at the end of the year, we will not be going through the plan with a red pen checking that you have done everything you said you would do. But I will expect you to maintain and update the plan regularly throughout the year, after discussion with me. If you find you have gone slower or faster than you expected and have to change dates in the timeline, or you discover in December that you were too ambitious and need to scale back, or you spot a new opportunity, that's fine - as long as you justify it to me and update your plan. What we want to see is that you have managed the project appropriately.

By science, I mean are you asking any research questions, or are you just building a product. If you are asking research questions, then you need to include in your plan a description of how you will determine the answer - e.g. is method A better than method B for solving this task? is it possible to improve on method C?
Even if your project is focused on building a product, you will still be expected to evaluate it, and consider different design choices. How quickly does this software respond to queries? What fraction of the intended behaviour can it actually meet? How easily can a user interact with the software? etc..


2. Weekly meetings - I expect to meet you once a week to review progress and to discuss ideas. We will arrange a regular time slot once we all know our timetables. In advance of each weekly meeting, you should send me a brief report on (i) what you have achieved in the previous week, (ii) what problems or difficulties you have encountered, and (iii) what you plan to do for the following week. This report can be plain text in an email - there is no need to spend time formatting it - but if there is something complicated you want my advice on, then the description needs to be legible. If you want to show me some running code on a PC, then you should bring a laptop if you have one.  You also need to bring a notepad to write down notes from the meeting - advice, suggestions, ideas, etc.. I will be taking notes, but they are for me.

If for any reason you have made no progress one week, and have nothing to discuss, then send me an email to let me know you are not coming. But if that happens too regularly, then I will start to ask questions. In general, though, the responsibility for monitoring your progress is your own - if you make little progress or stop coming to meetings or stop giving me updates, I will prompt you a couple of times, but after that I will stop chasing you. Note that there is a section in the marking scheme for us to assess the way in which you managed the project. If you are having any problems throughout the year, whether it is too many course deadlines, or outside work, or health problems or other personal problems, please let me know as soon as possible. If you don't tell us, we can't help.

3. Implementation, testing and evaluation - This is a computer science project, and so we do expect quality design and implementation and documentation of any software, proper testing of the software, and proper evaluation. To get a good project mark, the evaluation needs to be systematic and thorough - running your code on one example, or asking a couple of friends to tell you what they think of your software, is not enough. As part of the project plan, you need to think about how you will evaluate your work. Before the final submission. I will need a copy of the software, and instructions on how to install it and use it on whatever hardware or operating systems is appropriate.

4. The final report - As noted above, the report is important. Below is a description of what I think the final report should look like. I am sending this to you now so that it will help you in thinking about what your project will involve and in writing your plan. You also need to check if you have been given any documents by the department that may describe other requirements, and if they conflict, then you should follow the official department guidelines (but let me know). You don't have to follow my scheme exactly - you might find that not all of the subparts below apply to your specific project, you may want to omit some items or add your own, or even do it completely differently. But if you are going to do something radically different, then you should check it with me first.

Remember that communicating what you have done is a vital part of any project, and even the best software in the world will not get the credit it deserves if it is not described properly. Apart from anything else, most of those involved in the marking will only see your report and not the underlying software. So please don't keep coding up until two days to go, and then try to cobble a report together before the deadline. Secondly, the writing style is important. The report is meant to be a technical document that describes to other professionals what you have done - don't write it as a stream of consciousness, or as a diary, or as a series of personal thoughts and impressions. You will need to think carefully about how to present the information, about what the reader will want to know, and about what the reader will need to have explained to them in order to understand it. Don't dive straight into the details, and don't assume the reader understands the reasons for the project or the background.

The documentation should come in two parts:
A. Project report
B. Description of the software

A. describes the project for your Honours degree. My guess for size is about 30-50 pages, and you can write this using any package - Word, Latex, ... - I don't care, as long as it is well presented (but again, check the department's requirements). Note that all the sentences and phrases should be your own - don't cut and paste from papers, books or webpages. If you do use somebody else's words, make sure you give a clear attribution, otherwise it is plagiarism.

(i) Abstract - one page description of the whole thing, including a motivation and a summary of the conclusions
(ii) Introduction - what is involved? Why is it interesting? Describe the problem. What is the project meant to achieve? Are there any questions you are asking? (i.e. which of these three methods is fastest? Can this task be done in this way? etc)
(iii)Background - what are the standard textbook or research methods? What other software exists? Is there any gap in what is out there, or is there perhaps something wrong with what others are claiming, or do you want to verify that their claims are correct, or do you want to attempt to implement something that someone else has already built?

(if it is a software development project,
begin:
(iv) Design - how did you tackle it? What choices did you have, and what decisions did you make? You may want to include UML class or sequence diagrams here to explain a model of what you are going to implement. If you have implemented different versions for experimenting with, then you need to explain how they are different. If you are developing algorithms, then you should describe them here.
(v) Implementation - what main data structures did you use? If using a database, which one? How did you connect it to your program? If there are any significant details, give a description. You don't need source code in here, unless the details of the code are critical to understanding your project. If you used class or sequence diagrams in the previous chapter, then you don't need them here, unless they are showing important detail. If you have used someone else's design or pseudocode or implementation, clearly say so here.
(vi) Evaluation - how good is your software, and what did you do to evaluate it? If it has a user interface, have any users tried it out? What did they do, and what was their response? If it is a game, what circumstances did you try, and how well did it play? What experiments did you run to answer questions you posed at the start? What were the results?
end
else if it is a research project
begin:
(iv) Design: what are the different approaches you are considering? e.g. presenting choices to a user in style A or style B, or guiding an algorithm search using systematic method C or heuristic method D. What different metrics are important? e.g. standard work measures performance in runtime, but memory size is also important, and here is why.
(v) Implementation: what did you actually build to test the questions discussed in the previous chapter? How did you build it? [This chapter could be merged with the previous or the next one, if necessary]
(vi) Experiments: Describe the detail of the experiments you ran - how many people did you test it on? under what conditions? what exactly did you ask them to do? what problems did you test your algorithms on? how many times did you run your algorithms, on what hardware and OS? What results did you get, displayed in tables or graphs? What analysis can you do on the results, and what conclusions do they lead you to?
end)

(vii) Conclusion and Future Work - What are the main conclusions? how well did your approach work? What have  you learned? If you were starting again, would you do it differently? If you had another 6 months, what would you do?
(viii) Reference list - include at the end a list of books, papers, manuals, web pages etc that you have referred to in the report. Include as much information as possible, so that someone else can get hold of them. E.g. Author, Title, Book or journal title, date, page numbers, url, date url was last accessed, etc.
Format them consistently. The standard style is

[num] Author,Initial (year) "Title of Article", Details of where the article was published, including page numbers or url.   The year could also go at the end.

They should either be ordered (a) alphabetically by author, or (b) in the order they were referred to in the text.

In the text, refer to the papers in the following styles
(a) e.g. "Brown(2006) showed ..." or "This has appeared many times (e.g. Brown, 2006; Smith, 2007; Jones, 2008)"
(b) e.g. "Brown [3] showed ..." " or "This has appeared many times (e.g. [3,5,9])"

Depending on what form your project takes, you might think about including after chapter (i) in the project report a short walk-through of the system - show the reader what your software does, including some screenshots (this gives the reader a context for reading the rest of the report; without it, it is easy to get so bogged down in the details that the reader never gets the big picture of what you are doing)



B. is software engineering style documentation, and should be in an appendix and not in the main body of the report. The main criteria here is: how easy would it be for someone else to pick up your code and maintain it or extend it, using only your documentation? If you have used someone else's code, make sure this is clearly indicated - again, if you have used someone else's code but not credited it, it is plagiarism.
It should contain
(i) brief user manual - how does a user get started?
(ii) overview of the design - e.g. UML class diagrams, use cases etc.
(iii) separate text description of any significant parts
(iv) description of testing
(v) report of known bugs - when do they appear? how might you fix them?
(vi) javadoc produced html specs of the classes (if using Java)
(vii) code listings

All of part B should be on a CD, zipped tarfile, usb stick, or  department project archive if there is one - don't print it out.