File APIs for Java Developers
Manipulate DOC, XLS, PPT, PDF and many others from your application.
The moose likes Agile and Other Processes and the fly likes What should design document cover? Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login

Win a copy of Java Interview Guide this week in the Jobs Discussion forum!
JavaRanch » Java Forums » Engineering » Agile and Other Processes
Bookmark "What should design document cover?" Watch "What should design document cover?" New topic

What should design document cover?

Yongping Wang
Ranch Hand

Joined: May 15, 2001
Posts: 40
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.
Kishore Dandu
Ranch Hand

Joined: Jul 10, 2001
Posts: 1934
Irrespective of agile or not, I would suggest having use cases at the least. Then look into sequence, activity and class diagrams.

Some details about assumptions for each use case are also need to be documented for a clear picture.

SCJP, blog
Stan James
(instanceof Sidekick)
Ranch Hand

Joined: Jan 29, 2003
Posts: 8791
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
Warren Dew
Ranch Hand

Joined: Mar 04, 2004
Posts: 1332
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.
I agree. Here's the link:
subject: What should design document cover?
jQuery in Action, 3rd edition