Win a copy of Mesos in Action this week in the Cloud/Virtualizaton forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

What should design document cover?

 
Yongping Wang
Ranch Hand
Posts: 40
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
 
Kishore Dandu
Ranch Hand
Posts: 1934
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.
 
Stan James
(instanceof Sidekick)
Ranch Hand
Posts: 8791
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.
 
Warren Dew
blacksmith
Ranch Hand
Posts: 1332
2
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic