Documentation is an important part of agile software development but it is seen as a strategy that increases the overall project risk. It needs to be as efficient as possible and is written when that's the best way to achieve the goals.
When you use the TDD approach, you effectively write detailed specifications which encompass the requirements, architecture, and design and can later be used as the basis for your documentation. Documentation is best written towards the end of the iteration since you, then, know what you've actually built. Throughout the development, notes should be taken that can be "polished" just before the final delivery.
By waiting to document the process until it has stabilized, you reduce the cost and risk associated with documentation. Cost is reduced because you don't waste time documenting information that may change. Risk is reduced because there is less chance the existing documentation will be out of date.
There are some disadvantages to waiting until the end to write the documentation.
- You may have forgotten some of the reasons behind some of the decisions you made.
- The people who should write the documentation may have moved on to other projects.
- You may not have the funding to do the work.
- The will to write the documentation may no longer exist.
Documentation should be kept simple and concise offering an overview rather than detailed documentation. "Follow the Agile Modeling (AM) practices; Use the simplest tools, create Simple Content, and Depict Models Simply; when creating documentation." Keep your documentation as simple as possible while still meeting the needs of the customer and add to it as needed. Determining how a customer will be using the documentation will allow you to document as simplistically as possible. The more detailed and lengthy documentation is, the more likely it contains errors and will not be properly updated when necessary.
Agile documentation should be "just barely good enough to fulfill its purpose". It should consist of a large document composed of many smaller ones. It should fulfill the goal of the project. You should work closely with the customer to be sure you create a document that meets their requirements. You should ask the customer:
- What they do
- How they do it
- and how they want to use the documentation
Documentation is evolutionary. You should write a little bit, show it to someone, get feedback, and then iterate. This allows you to write your documentation for your audience.
Remember to treat documentation like any other requirement of the iteration. It should be included in your estimate along with the other work items.
Finally, documentation should not be technical. It is often advantageous to write it with a partner.
From Agile Documentation by Scott W. Ambler
*Recommended Resources*
|
|
|
|
|
|
|
|
|