]
]Writing technical documents is an essential part of software engineer's life. Most of us would rather be coding, but we still have to do it. That is why the project report is a main deliverable in a project course. As you will soon realize, producing a good project report is hard work (sometimes, harder than coding), and we may not get it right in one shot. That is why an iterative approach to writing the report can work better. i.e., show the intermediate versions to the supervisor (if allowed), and get his/her feedback on your writing style, level of details etc., based on which you can improve subsequent versions of the report.
First, let us remind ourselves of the main objective of the project report:
Given below are some tips to help you write a better project report:
Eventually, your project report will be read, and evaluated. There is no guarantee that the evaluator will read the whole report end-to-end with the same intensity. That is why it is important to give a good first impression. Pay particular attention to the beginning part of the report. A top-notch beginning will make the evaluator read the rest with a positive frame of mind. If your first chapter is lousy, you chances of getting a good grade takes an immediate nose dive. By the same logic, pay special attention to the beginning part of each chapter as well. Of course a lousy report will not get a good report if you slapped on a spruced-up opening chapter on it.
While we are on the topic of making good impressions, note that a well-formatted, crisp-looking report always has an edge over a one that is not. A student project report does not require publication quality formatting. But it does not hurt to use a clean, tidy layout and easy-to-read fonts.
This goes without saying for any writing. But what is the right level of detail for a student project report, especially when describing technical details of the project? A safe bet is to write as if it is meant for a new programmer joining your team in the near future. Not too detailed, since the new guy will eventually look at the code. Not too high level, as you want the new guy to really understand how your software works.
Most programmers tend to program in bottom-up fashion. But when writing the project report, a top-down explanation is easier to understand than a bottom up one. Let's say you are explaining a system called SystemFoo with two sub-systems: front-end and back-end. Start by describing the system at the highest level of abstraction, and progressively drill-down to lower level details. Given below is an outline for such a description.
[First, explain what the system is, in a black box fashion (no internal details, only the outside view)]
SystemFoo is a ....
[Next, explain the high-level architecture of SystemFoo, referring to its major components only]
SystemFoo consists of two major components: front-end and back-end
front-end's job is to ... back-end's job is to ...
And this is how front-end and back-end work together ...
[Now we can drill down to front-end's details]
front-end consists of three major components: A, B, C
A's job is to ... B's job is to... C's job is to...
And this is how the three components work together ...
[At this point you can further drill-down to the internal workings of each component. A reader who's not interested in knowing those nitty-gritty details can skip ahead to the section on back-end]
...
[Here, we can drill down to back-end's details]
...
If you take the attitude "as long as it's accurate and complete, it's up to the reader to make sense out of it", your report is not going to be very effective in achieving the desired outcomes. It is in your best interest to make the report as easy (and pleasant) to read as possible. Some things that could help here are...
When evaluating a project report, students usually get credit for software engineering "lessons learned", even if the lesson came at the expense of a mistake. It is in your interest to keep notes about such lessons you learned throughout the project, and include them in the report. If you don't keep notes, most likely some of them will be forgotten over time.
Providing details such as given below will demonstrate how well you learn
from experience:
What was the problem faced? What were the alternative solutions you considered?
Which alternative did you choose? Why did you choose
it? Which ones did you try and discarded? Did you solution work? Looking back, would you have chosen a different alternative?
What lesson did you learn from facing the problem? Could you have avoided the
problem altogether?
Designs often evolve over the course of the project. Following the same logic above, we should also describe those changes we did, why did we change it, what did we learn from it, etc. However, take care not to cram everything in one place. You are better off describing the final design in one place, and design changes you did in another place (e.g., under the heading "refactoring").
If it can be said in 29 pages, don't use 30 pages even if the page limit for the report is 30. Evaluators like it when the report is short. However, do not skip important details (because, if you didn't write it down, it didn't happen).
It is enough to very briefly mention the stuff you are usually expected to do anyway. If you did not mention them at all, there is a small risk of the evaluator assuming that you didn't do it (because, if you didn't write it down, it didn't happen). But if you think some part of your design or some aspect your process is special, make sure your emphasize that part/aspect sufficiently.
If you make a claim, make sure you support it sufficiently, or you will not get credit for it.
For example, simply claiming that "We made our system faster" will not earn you marks. You should support it by answering the following questions: What improved the speed? Why did you think that change would improve the speed (provide analytical arguments)? Why did you think the change actually made the system faster (provide performance data)?
Different parts of the project report are written by different team members. Yet it is important that the end result is a single cohesive document. If you have not been given a template to base your report on, start by creating such a template, which should take care of the cohesiveness issue to some extent.
However, you still have to ensure consistency across the whole report:
To begin with, make the formatting consistent. This can be easily done by using "styles" (see here to find out how).
It is more difficult, and perhaps more important, to keep other aspects consistent, such as the use of upper/lower case (it is rather annoying to see ad hoc use of UPPER and lower case for the same word. e.g., BOOL vs bool vs Bool), use of terminology, the level of details, and the style of explanations.
It helps to appoint one team member to oversee the quality of the report (i.e., a documentation guru - see here to learn more about gurus). Of course, you should also allocate time for this person to do his/her job. i.e., to collate various parts done by different team members, weed out inconsistencies, and improve the cohesiveness of the report.
Embarrassingly, most of us don't know how to use a word processor effectively. If you find yourself doing at least one of the following during report writing, have a look at this document; it will save you a lot of rework.
Describing algorithms (e.g., a query evaluation strategy) in words is hard work. Here's a small trick that is really useful:
Step one: Instead of writing it as a report, create a PowerPoint presentation to describe the same. For each slide, write down what you are going to say during the presentation, using the "notes" feature of PowerPoint. Do a mock presentation to your teammates, using the slides and the accompanying notes. Ask your teammates to interrupt you and ask questions when things are not clear. Refine slides/notes so that such questions are no longer need to be asked. Iterate until you arrive at a near perfect presentation.
Step two: Convert the presentation into a document. Slide-notes and slide-text will be the text in your document. You can transfer diagrams in slides by embedding slides directly in a word document (see
here to find out how). If the presentation was
understood well by the audience, the report will be understood well by the reader too. As an additional bonus, now you already have slides for the
project presentation, and you know how to present them too!
If you plan to "finish the coding first and write the report afterwards", you are heading for trouble. First, coding rarely finishes on schedule. Second, project report takes more effort than you think at first (if you want to write a good report, that is). As a result, you are very much likely to find yourself squeezed between a project running behind schedule, and a looming deadline.
Evaluators usually start the final grading by reading the report. If that doesn't turn out to be a pleasant experience, that's going to affect how the evaluator will look at rest of the stuff.
Further resources
Any suggestions to improve this book? Any tips you would like to add? Any aspect of your project not covered by the book? Anything in the book that you don't agree with? Noticed any errors/omissions? Please use the link below to provide feedback, or send an email to damith[at]comp.nus.edu.sg
 |
Sharing this book helps too! |
---| This page is a part of the online book Tips to Succeed in Software Engineering Student Projects V1.8, 3rd Sept 2008, Copyrights: Damith C. Rajapakse |---