]
]Writing technical documents is an essential part of software engineer's life. Most of us would rather be coding, but we still have to document things. That is why the project documentation is often a main deliverable in a project course. As you will soon realize, producing a good project documents is hard work (sometimes, harder than coding) and we may not get it right in one shot. That is why an iterative approach to documentation can work better. i.e., show the intermediate versions to the supervisor (if allowed), and get his/her feedback on your writing style and level of details etc. based on which you can improve subsequent versions of the documents.
First, let us remind ourselves of the main objectives of different project documents:
Given below are some tips to help you write a better project documents:
Eventually, your project documents will be read and evaluated. There is no guarantee that the evaluator will read the whole document 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 document. A top-notch beginning will make the evaluator read the rest with a positive frame of mind. If your first chapter is lousy, your chances of 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 document will not get you a good grade just because 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 document always has an edge over a one that is not. Your project documents do 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. For example, what is the right level of detail for a developer document? A safe bet is to write as if it is meant for another student who will be 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.
All too often we write documents but do not read them later. If you cannot force yourself to read it, how can we expect someone else to read it?
Read whatever you wrote to see how it appears to your audience. If you let some time elapse before reading it, it will be easier to switch from writer mindset to reader mindset.
When writing project documents, a top-down explanation is easier to understand than a bottom-up one. Let us 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 is accurate and complete, it is up to the reader to make sense out of it", your documentation is not going to be very effective. It is in your best interest to make the document as easy (and pleasant) to read as possible. Some things that could help here are...
When evaluating a project, 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 project documents. If you do not 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 your 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").
Most of your project documents will need input from multiple teammates. You can use tools like GoogleDocs to works on the same document in parallel. Since such tools often track revision history, it will even help the supervisor to know who did which part of the document.
When you have to describe several similar algorithms/designs/APIs/etc., do not simply duplicate large chunks of text. Instead, have the similarity described in one place and emphasize only the differences from elsewhere. It is very annoying to see pages and pages of similar text without any indication as to where the differences are.
Aim for "just enough" documentation. If it can be said in 29 pages, do not use 30 pages even if the page limit for the document is 30. Evaluators like it when a document 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 did not do them (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 else 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 a project document may be 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 document on, creating such a template should take care of the cohesiveness issue to some extent.
However, you still have to ensure consistency across the whole document:
To begin with, make the formatting consistent. This can be easily done by using "styles" feature of MSWord (other word processors are likely have an equivalent feature).
It is more difficult, and perhaps more important, to keep other aspects consistent. For example, 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 a project document (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 document.
Embarrassingly, most of us do not know how to use a word processor effectively. If you find yourself doing at least one of the following, have a look at this document; it will save you a lot of rework.
Describing an algorithm in words is hard work. Here's a small trick that is really useful:
Step one: Instead of writing it as a document, create a PowerPoint presentation to describe the same. For each slide, use the "notes" feature of PowerPoint to write down what you are going to say during the presentation. 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 needed. 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 document 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 documents afterwards", you are heading for trouble. First, coding rarely finishes on schedule. Second, documentation takes more effort than you think at first (if you want to write a good document, 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 project documents. If it turned out to be an unpleasant experience, that is surely going to affect how the evaluator will look at rest of the stuff.
When the course does not have a system to rigorously evaluate your product (e.g., by way of an extensive test suite), the importance of project documents becomes all the more important. All the hard work you put into the product can be undermined by the bad impression given by your project documents.
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.9, Jan 2009, Copyrights: Damith C. Rajapakse |---