Question for you guys, Our team is going to try Agile methodology to develop a proejct. Since it is new to us (well I admit the methodology is not new) I am not sure what the design document should contain. Please direct me. Thanks. Y.Ping
See the Uses of Architecture Documentation that I "borrowed" from SEI. This gives you some idea of who might want to read your documents. And that's the true key. Who needs to know what? And for which of those audience+content combinations is a document the best way to communicate to them? Face-to-face communication is far more efficient, but not as durable. Anything you can extract from the source code itself is most likely to be true and accurate. You'll have to find your own balance.
One thing I don't see mentioned there is something I just went through this morning. In some shops it is important to keep a lot of people outside the project informed of what's going on. Maybe capacity planning, deployment, and production support. Maybe more or fewer in your world.
A good question is never answered. It is not a bolt to be tightened into place but a seed to be planted and to bear more seed toward the hope of greening the landscape of the idea. John Ciardi
If you are really trying to follow agile methods, it's not clear that you should even have a formal design document. The point of agile methods is to be able to follow shifting needs with agility.
In my opinion, the Javadoc for the code is the best place to put the design documentation. Don't forget the HTML files describing each package.
You may still need some requirements documentation. In my opinion, use cases work well with agile programming as they break down the requirements in a way that allows the requirements to be implemented incrementally.