Design document: to write or not to write

One of the tenets from agile manifesto says "Working software over comprehensive documentation". Unfortunately many lazy (agile) developers use this manifesto to excuse that "we don't have to write documentations at all". Some developers claim that they are agile when they follow the no-documentation principle without practicing other agile principles (such as early & frequently deliveries.)

I believe that writing simple documents (such as use-case, requirements list and architecture design) is still beneficial yet in the agile context.

There are several benefits of a written design document (whether as up-front design or during the iterations):
• you can distribute it to many people (also across the continent) to get feedbacks, so you don't have to explain again & again orally.
• To get feedbacks in the early phase while you defining architecture is important. Despite using agile process, you can't denied that the cost of changing your initial architecture decisions will get more and more expensive as you proceed in the development phase. The cost of repairing a wrong decision in the early phase (architecture) is expensive. You can get better feedback by writing the requirements & the architecture clearly in documents.
• if you don't write you can easily overlook/forgetting important details (beware: the devil is in the details), other people can review the list in your documents and add/comment.
• You can postpone some risky decisions and delay the design which most likely to change, but at least you need to mention the indecisive issues, the risks and the assumptions in your design documents, it will serve like a checklist that you/others can refer later to discuss.
• If you leave the company/project or if you delegate the project to others, the next person doesn't have to start from scratch. It will be easier also for the next people who have to extend the finished product, so they understand the reasons behind you decisions.

Please read my blog about "Software architecture design document"
http://soa-java.blogspot.com/2011/06/software-architecture-design-document.html

How about your experiences with trade-off between the rigorous (RUP) documentations & agile simplicity in your organization? Please write your comments.

---

Source: Steve's blog http://soa-java.blogspot.com

Reference:
Agile Manifesto