Sharing this book helps too!
Writing technical documents is an essential part of a software engineer's life. Most of us would rather be coding, but we still have to document things. That is why documentation is often a main deliverable in a project course. As you will soon realise, producing 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 feedback on your writing style and level of details, etc. and improve subsequent versions of the documents based on this.
Project documents feature heavily in project grading. If reading it turned out to be an unpleasant experience, it is surely going to affect how the evaluator will look at the rest of your project. When the course does not have a system to rigorously evaluate your product (e.g. by way of an extensive test suite), project documents become even more important. All the hard work you put into the product can be undermined by the bad impression given by your project documents.
First, let us remind ourselves of the main objectives of different project documents:
Note that in smaller projects you might be asked to produce a single document that combines all three aspects.
Given next are some tips to help you write better project documents:
Yes, evaluators will read your project documents, but there is no guarantee it will be read beginning-to-end with the same intensity. That is why it should 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 take 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 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 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 font.
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 you expect someone else to read it? Read whatever you wrote to see how it appears to your reader. If you let some time lapse before reading it, it will be easier to switch from a writer mindset to a reader mindset.
When writing project documents, a top-down breadth-first 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 is not interested in knowing these 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 'it is good enough to be accurate and complete', 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.
Most of your project documents will need input from multiple teammates. You can use tools like GoogleDocs to work 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 emphasise only the differences in other places. It is very annoying to see pages and pages of similar text without any indication as to how they differ from each other.
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.
It is enough to very briefly mention the stuff you are usually expected to do anyway. If you do not mention them at all, there is a small risk of the evaluator assuming that you did not do them. But if you think some aspect your project is special, make sure you emphasise that 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 do 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. Still, it is important that the end result is a single cohesive document. If you have not been given a template for your document, creating such a template yourself should increase the cohesiveness of the final document.
However, you still have to ensure consistency across the whole document:
Describing an algorithm in words is hard work. Here is a small trick that is really useful, especially if the project presentation too includes a description of the same algorithm:
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. 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 likely to find yourself squeezed between a project running behind schedule and a looming deadline.
Grammar errors and spelling mistakes in user documentation may be interpreted by potential users to mean the product is of equally low quality. Avoid such mistakes as much as possible, although this may be hard for non-native speakers of the language. At least check for things like consistent capitalization, etc. Dialogue boxes, error messages, and other text produced from within the software itself are parts of the user documentation and should be written with due care. In fact, it is a good idea to put all such text in one file for easier proof reading.
User documentation is a contract with the user. Please make sure the software behaves exactly as described in the software. It is very common for the software to evolve without the user guide catching up.
Make the user guide as simple to read/follow as possible. In particular, use users' language, not developer jargon. It is a good idea to have both a 'quick start' guide written in tutorial style and a more detailed user manual written in reference style.
The developer guide exists to help other developers learn just enough to start working on a particular part of the software. After giving a high-level view of the system, you can systematically drill down to more details of each component, explaining their external behaviour (i.e. the API), the internal structure, and how the internal structure accomplish the required behavior.
Note that unless it is required by the instructor, it is not a good idea to have separate sections for each type of artifact, such as 'use cases', 'sequence diagrams', 'activity diagrams', etc. Such a structure indicates that you do not understand the purpose of documenting and is simply dumping diagrams without justifying why you need them.
Many things that happened during the project is not readily visible from the final product. The downside of this is some of those things could earn you extra marks if only you communicated them to the evaluator in the right light. How will the evaluator know that you went through two alternative designs before you settled on the final one, unless you have documented it somewhere? Unfortunately, most of things that happened during the project is forgotten by the time you come to the final evaluation. The remedy is to keep brief notes of all significant things the project goes through. At the end, you can select which ones can earn you more credit and should be explained in more details.
A good project course is more about 'learning something' than it is about 'producing something'. At the end, you are trying to prove that you did the project well, but also, and more importantly, you can do it even better in the future (that is, you have learned something from this experience that made you a better software engineer). How well you learn from experience is a gauge of your maturity, and deserves a lot of extra credit. Unfortunately, most lessons are learnt and used without even realizing it. Please make an extra effort to record them somewhere and present them to the evaluators in some form.
A project course expects you to learn something at every step of the project. When things go wrong, not only should you correct the mistakes, but you should learn why it went wrong, and should reflect on how to avoid the same mistake in the future. When things go well, you still try to figure out why, and how to repeat the same success in the future. A good practice is to have a small 'post-mortem' session after each iteration to figure how you can do better in the next iteration.
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 discard? 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?
Of course, there is not enough time to make every mistake possible and learn from it. A smarter way to learn is to learn from other people's experience. Learn, and use, famous quotes related to software engineering. A quote contains a gem of wisdom that has stood the test of time. They are easy to remember, and impressive to use. Read books/articles that are based on software engineering experiences (not those thick theory books). Most of them contain lessons learned from decades of real software engineering experience. They contain interesting anecdotes, and are often written in an easy-to-read story-book style. While learning from these sources has its own benefits, showing that you did can earn you more marks.
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 from the free online book Practical Tips for Software-Intensive Student Projects V3.0, Jul 2010, Author: Damith C. Rajapakse |---