A common agile practice is to defer the creation of all documents as late as possible, creating them just before you need them.  For example, system overviews are best written towards the end of the development of a release because you know what you’ve actually built.  Similarly, the majority of user and support documentation is also best written towards the end of the lifecycle.  Figure 1 compares the traditional and agile approaches to documentation, showing the relative total amount of effort invested in creating and maintaining documentation throughout the SDLC.  Fundamentally, the strategy is to wait until the information has stabilized before you capture it in documentation.  It is risky to capture speculative information, such as requirements or design details, early in the lifecycle because those details are likely to change.

Figure 1. Documentation throughout the software development lifecycle.

It's interesting to note the differences in the two strategies:

1. Agilists model and plan early in the project, but they don't write detailed documents. Agilists will invest a bit of time at the beginning of the project to envision the initial requirements and the initial architecture.  They do this because people will ask questions such as what are you going to do, how much will it cost, how long will it take, and how are you going to build it.  The implication is that you need to do some high-level requirements and architecture modeling, but that doesn't mean that you need to write mounds of detailed specifications.  Get the value out of modeling, which is to think things through, without the cost of needless documentation.  Agilists will also create a high-level plan showing projected delivery dates, major dependencies, and so on.
2. Agilists still create detailed specifications.  Agilists capture the details on a just-in-time (JIT) basis, not up front.  They also prefer to write executable specifications in the form of tests, not static documents.  When you take a Test-Driven Development (TDD) approach this is quite easy to achieve.  In the end, Agilists often do more specification than traditionalists but we do it in a different manner.
3. Agilists still write supporting documents.  Supporting documentation, such as user manuals, operations manuals, and support manuals, are an important deliverable of any system development project.  Agilists, like traditionalists, will write these documents towards the end of the lifecycle once the system has stabilized.  However, because Agilists treat documentation like a requirement we will estimate the effort to write it and ask our stakeholders to prioritize it along with all other requirements.  Because of this greater level of stakeholder participation and control Agilists will tend to be more efficient than traditionalists when it comes to that sort of documentation (when you put a visible price tag on things people get really smart really fast over how they invest their money).
4. Agilists still write system overview documentation.  There will still be some need for high-level overview documentation for the people who will need to maintain the system.  However, because Agilists write high-quality code than traditionalists and have a regression test-suite for their code (which in effect is the detailed specifications for the system) you will find that you only need a concise overview consisting mainly of critical high-level diagrams.  The greater discipline of Agilists, and the resulting higher levels of quality, result in less need for detailed documents (which are invariably out of date anyway, further contributing to the quality challenges on traditional projects).
5. Agilists have a lower cost curve.  Not only is the agile curve in Figure 1 lower, it is also less steep.  By documenting early in the lifecycle traditionalists incur increased documentation maintenance costs throughout the lifecycle.

By waiting to document information once it has stabilized you reduce both the cost and several risks associated with documentation:

1. Financial risk.  Cost is reduced because you won't waste time documenting information that changes, which in turn motivates you to update the documentation.  If you write documentation containing information which has not yet stabilized then you are at risk of having to rework the documentation once the information has changed.  In other words, you do not want to invest much time documenting speculative ideas such as the requirements or design early in a project.  Instead, wait until later in the lifecycle when the information has stabilized and when you know what information is actually useful to you.  The implication is that your documentation effort may be a few iterations behind your software development effort.
2. Accuracy risk.  Accuracy is improved because there is significantly less chance that your existing documentation will be out of date. 

However, this doesn't mean that all documentation should be left towards the end because there some risks are increased:

1. Completion risk.  You may not complete the required documentation due to lack of resources (financial, time). To counteract this risk make the creation of those documents explicit requirements which should be prioritized and estimated like any other requirement.
2. Accuracy risk.  You may forget some information.  To counteract this risk you might still want to take notes for these sorts of documents throughout development so that you don't lose critical information.  These notes may be nothing more than point-form information as there is no need to "polish" documents until just before final delivery of them.

Recommended Resources

		Agile Documentation describes a collection of patterns for writing effective system documentation.
		The Object Primer 3rd Edition: Agile Model Driven Development with UML 2 is an important reference book for agile modelers, describing how to develop 35 types of agile models including all 13 UML 2 diagrams.  Furthermore, this book describes the techniques of the Full Lifecycle Object Oriented Testing (FLOOT) methodology to give you the fundamental testing skills which you require to succeed at agile software development.  The book also shows how to move from your agile models to source code (Java examples are provided) as well as how to succeed at implementation techniques such as refactoring and test-driven development (TDD).  The Object Primer also includes a chapter overviewing the critical database development techniques (database refactoring, object/relational mapping, legacy analysis, and database access coding) from my award-winning Agile Database Techniques book.
		Agile Modeling: Effective Practices for Extreme Programming and the Unified Process is the seminal book describing how agile software developers approach modeling and documentation.  It describes principles and practices which you can tailor into your existing software process, such as XP, the Rational Unified Process (RUP), or the Agile Unified Process (AUP), to streamline your modeling and documentation efforts.  Modeling and documentation are important aspects of any software project, including agile projects, and this book describes in detail how to elicit requirements, architect, and then design your system in an agile manner.

7. Let Me Help

I actively work with clients around the world to improve their information technology (IT) practices as both a mentor/coach and trainer.  A full description of what I do, and how to contact me, can be found here. 

 

Copyright © 2001-2009 Scott W. Ambler This site owned by Ambysoft Inc. Agile Data (AD)  |  Agile Unified Process (AUP)  |  Enterprise Unified Process (EUP)  |  My Writings   |  IT Surveys