So going a little deeper....
The arguments for not producing design documentation can be broken into a number of distinct areas:
- The team knows what it is coding therefore has no need for documentation
- To maintain qualitiy documentation costs too much
- The client is only interested in the code not the design
- Well written/commented code menas no need for design documentation
Lets look at each of these in turn....
The team knows what it is coding therefore has no need for documentation
We have all been there and I'm sure we all have the scares both physical and mental as why this is not true!! Worse still a number of us will have had to pick up the pieces of maintaining such a development. A team will be more productive and produce better code if they understand the design from the start. It is like starting a race with no other directions other than run! The response is usually - 'Which way??' or 'How fast'. Where as a better result is when we say - 'When the race starts I want you to run clockwise around the track as fast as you can...'
To maintain qualitiy documentation costs too much
With clear guidelines coupled with good templates and a sensible approach this just isn't true. Documentation is useful not a hinderance.
The client is only interested in the code not the design
Again, not true, the customer is very intrested in what his money has bought. A complete and documented solution. This becomes even more important when he wants to change the solution. If we believe the customer does not value design documentation this is not an excuse not to do any but more an invitation in educating the customer in its value.
Well written/commented code menas no need for design documentation
We need design documentation long before code, moreover it has value before we even start coding. Design documentation is done at an architectural level not at a code level. We cannot possibly consider architectual issues down at the level of code.
What is true that well commented code adds to the overall documentation of the solution and is part of a professional approach.
To conclude
Design and its associated documentation must be a precursor to implementation. This approach has huge benefits - we can produce more maintainable and more complex solutions and do it in a controled manner.
Consider one final thing - would a bridge builder build a bridge without design documents? Well the answer to this is yes and no. Yes if we want a quick and ready solution to crossing the river the once and no if we want to keep crossing the river dsay in and day out....
Design documentation must:
- Be part of the development cycle – don’t treat it as an afterthought.
- Make sure its meaningful
- Use loads of diagrams - a picture is worth a thousand words
- Architectual documents - describe all aspects the architecture will encounter
- Try to capture dynamic behavior rather than static structure in fuctional documentation