Agile Best Practice: Document Continuously

Scott W. Ambler + Associates
 
   Home  |  AMDD  |  Best Practices  |  Architecture  |  Requirements  |  Analysis  |  Design  |  Documentation  |  Models  |  Modeling Style  |  Contact Us  |  Announcements  |  FAQ
Recently reviewed If your goal is to have potentially shippable software every sprint as they say in Scrum, or better yet to have a potentially consumable solution every iteration as we say in Disciplined Agile Delivery (DAD), then you will need to keep your deliverable documentation in sync with your software/solution -- in other words, write deliverable documentation continuously throughout the project.  Your other option is to leave the finalization of your deliverable documentation to the end of the project, to document late.  

 

I've been using the term "deliverable documentation", but what does that mean?  Deliverable documentation is the documentation that you need to deliver to your stakeholders as part of your overall solution.  This will of course vary between projects, but deliverable documentation typically includes user manuals, training materials, operations manuals, support manuals, and system overviews.  It typically does not include requirements specifications or design specifications, except of course in regulatory situations where such documentation is required or in contract negotiations where it's required as part of the contract.  Of course, with all such artifacts, I highly suggest following the best practices of agile documentation.

Here are some good heuristics to document continuously in an effective manner:

  1. Wait for the information to stabilize. Write the documentation after you've done the majority of the development work, in other words towards the end of the iteration.  If you document information that isn't yet stable, you run the risk of having to rework your documentation.
  2. Write documentation during the iteration with long iterations.  With "long" iterations, say four weeks or more, you have sufficient time for information to stabilize and thereby capture it during that iteration.
  3. Write documentation the following iteration with short iterations.  With "short" iterations, two weeks or less, it's unlikely that the information will stabilize in time for you to complete the documentation.  To remain efficient as possible you should consider writing the deliverable documentation for iteration N during iteration N+1.  With medium length iterations (two to four weeks) you will need to experiment to identify which approach works better for you.

Note that with this practice many teams will include criteria around updating deliverable documentation in their definition of done for the iteration.   In other words, documentation becomes part of the acceptance criteria for determining whether a work item (such as a user story or defect report) has been fully implemented.  This reflects the Disciplined Agile Delivery (DAD) philosophy of solutions over software.

 

Risk Profile of this Practice

By writing deliverable documentation continuously throughout the project, you address the following risks:

  1. Delivery risk.  By writing the documentation in sync with the rest of the solution, you know you have sufficient documentation to support what you've built to date.  The implication is that your solution will in fact be potentially shippable at the end of each iteration.
  2. Accuracy risk.  Because the feedback cycle between doing the work and documenting what you did is short it is much more likely that you will remember the critical details which need to be captured.

However, there are three risks which are potentially increased by this practice:

  1. Financial risk.  Because the requirements are likely to evolve throughout the project, you will need to update the deliverable documentation to reflect those changes.  You are in effect "travelling heavy" from an agile point of view by documenting continuously.
  2. Schedule risk.  It takes time and effort to write and maintain this documentation, and any rework of the documentation resulting from evolving requirements in effect impacts your schedule due to the required rework.
  3. Accuracy risk.  Sadly, it's easier to write about documenting continuously than it is to do it.  It's common that agile teams will put off writing documentation until they have time to do so, in effect moving towards the document late practice instead of this one.
Agile Documentation

 

Recommended Resources

 

Agile Documentation   Agile Documentation describes a collection of patterns for writing effective system documentation.
The Object Primer 3rd Edition: Agile Model Driven Development (AMDD) with UML 2   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   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.

 

Let Us Help

We actively work with clients around the world to improve their information technology (IT) practices, typically in the role of mentor/coach, team lead, or trainer.  A full description of what we do, and how to contact us, can be found at Scott W. Ambler + Associates.


Disciplined Agile Delivery: The Foundation for Scaling Agile Agile Modeling: Practices for Scaling Agile Agile Data: Practices for Scaling Agile EnterpriseUP: Agility at Scale AgileUP: Towards Disciplined Agile DeliveryAmbysoft Inc. Software Development Practices Advisor Scott Ambler + Associates Follow @scottwambler on Twitter!


Copyright © 2010-2012 Scott W. Ambler

This site owned by Ambysoft Inc.