Channels ▼


Dr. Dobb's Agile Update 11/23

Documenting Late

By waiting to document information once it has stabilized at the end of a project, during the transition/release phase, you reduce both the financial and accuracy risks associated with documentation. When it comes to financial risk, cost is reduced because you won't waste time documenting information that changes, thereby requiring costly updates. 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. Furthermore, accuracy risk is decreased because you are focusing on what you actually built and did, not on what you speculated would build and how you would do so.

With the Document Late practice some risks are potentially increased. First, delivery risk increases because 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. Second, accuracy may increase because 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.

I’d like to leave you with several important observations about agile delivery teams and their approach to specification and documentation. First, agilists will invest a bit of time at the beginning of the project to envision the initial requirements and architecture as well as produce a high-level plan. Except in regulatory environments they typically won’t take on the risks associated with documenting these things in detail. Second, agilists still create detailed specifications, but they do so on a just-in-time (JIT) basis, not up front. They also prefer to write executable specifications in the form of tests or sophisticated models, and often do more specification than traditionalists in the long run. Third, agilists still write supporting documents such user manuals, operations manuals, support manuals, and even system overview documentation. Fourth, agilists have a lower cost curve in part because of their streamlined specification documentation strategies. Don’t let anyone tell you different.

State of the IT Union Survey

We invite you to fill the December 2010 edition of Scott Ambler's “State of the IT Union" Survey (the URL is The goal of this ongoing survey series is to find out what IT professionals are actually doing in practice. The survey should take you less than 5 minutes to complete, and your privacy will be completely protected.

At the end of the survey, you will be given the chance to be entered into a draw for one of ten copies of Glitch: The Hidden Impact of Faulty Software by Jeff Papows, published by Pearson. This book is a business technology expose that examines the technical, business, and consumer impact of software glitches that continue to erode brands, consumer confidence, productivity, and profitability.

The results of this survey will be summarized in a forthcoming newsletter. Furthermore, this is an open survey, so the source data (without identifying information to protect your privacy), a summary slide deck, and the original source questions will be posted at so that others may analyze the data for their own purposes. Data from previous surveys have been used by university students and professors for their research papers, and hopefully the same will be true of the data from this survey. The results from several other surveys are already posted there, so please feel free to take advantage of this resource.

Hot Links

The Danger of Detailed Speculations summarizes the evidence around how detailed specifications can increase, not decrease, the risk on your IT projects.

Agile/Lean documentation strategies are overviewed at

The Executable Specifications agile practice is described at

Agile Modeling’s Document Late practice is described in detail at

Agile Modeling’s Document Continuously practice is described in detail at

The Disciplined Agile Delivery (DAD) is a hybrid process framework which extends Scrum with strategies from Extreme Programming (XP), Agile Modeling (AM), Unified Process (UP), Lean, and several others.

In July 2008 DDJ ran the Modeling and Documentation Practices on IT Projects Survey, the detailed results for which are posted at

The September 2009 DDJ State of the IT Union Survey explored issues around the quality of deliverable documentation being produced by delivery teams. The detailed results are posted at

Ambysoft’s November 2010 Agile State of the Art Survey explored several aspects of what agile teams are doing in practice. The results are available at

You can follow Scott Ambler on twitter.

Related Reading

More Insights

Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task. However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.