Channels ▼


Newsflash: Agilists Write Documentation!

Agile Documentation

Dr. Dobb's Modeling and Documentation survey revealed that there's not a lot of difference between the various development approaches when it comes to deliverable documentation. After all, a deliverable is a deliverable. So, the fears concerning the mythical lack of documentation on agile projects appear to be unfounded, forcing the traditionalists who are still holding out to find another excuse for not adopting agile strategies. As you see in Figure 2, the survey did show that agilists are slightly less likely than traditionalists to produce system overview documentation, although slightly more likely to produce operations documentation. I suspect that there is less of a need for system overview documentation because agilists have a greater tendency to produce higher quality code as the result of refactoring and test-first practices. Agile teams may also require less documentation due to the practice of writing executable specifications.

The Practices and Principles Survey explored how people communicate with one another on agile project teams, asking how effective various ways for communicating with stakeholders are. In order of most effective to least effective, the score for each technique is a weighted average between 5 (very effective) and -5 (very ineffective), it found the following:

  1. Face to face (F2F) discussion (4.06)
  2. F2F at whiteboard (3.46)
  3. Overview diagrams (1.89)
  4. Overview documentation (1.86)
  5. Video conferencing (1.62)
  6. Teleconference calls (1.51)
  7. E-mail (1.32)
  8. Detailed documentation (0.16)
  9. Online chat (0.15)

There are several interesting observations to be made. First, the belief that traditionalists have in the value of detailed documentation can be understood as it has neutral value, regardless of all the rhetoric that we hear in the agile communities surrounding the evils of detailed documentation. Second, sharing overview documentation with stakeholders does seem to have some merit, although it is nowhere near as effective as direct communication, clearly belying some agile prejudices against documentation. Third, media richness theory, which Alistair Cockburn introduced the Agile community to (see, pretty much holds. The "hotter" the communication channel, generally the more effective it appears to be. Fourth, these results may explain why distributed agile projects appear to be riskier than colocated projects because the greater the distribution, the more restricted your communication options become. Dr. Dobb's 2008 Agile Adoption Survey ( found measurable differences in the success rates of distributed agile projects—83 percent for colocated agile teams, 72 percent for near-located agile teams, and 60 percent for far-located agile teams.

[Click image to view at full size]

Figure 2: The chance that a key documentation deliverable will be produced by teams following various software development paradigms.

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.