Dr. Dobb's is part of the Informa Tech Division of Informa PLC

This site is operated by a business or businesses owned by Informa PLC and all copyright resides with them. Informa PLC's registered office is 5 Howick Place, London SW1P 1WG. Registered in England and Wales. Number 8860726.

Channels ▼


Newsflash: Agilists Write Documentation!

Scott is Practice Leader Agile Development for IBM Rational.

You've likely heard, and worse yet spread, some of the common myths around modeling and documentation on agile projects. For example, there's the myth that Agilists don't do any architecture, something that flies in the face of the fact that all systems have architectures regardless of the development paradigm used to create them. Another myth is that Agilists don't do up-front requirements modeling, yet when was the last time you saw a software development get funding without an indication of what was going to be built? Agilists apparently don't write documentation either, having magically convinced end users that they don't need user manuals, operations and support people that they don't need any sort of documentation, and the maintenance team that they don't need any sort of overview documentation. The list of things that agilists are supposedly getting away with is truly impressive, so needless to say, I believe that it is abundantly clear that these myths and misunderstandings need to be cleared up. This month I summarize the results from two surveys, one that focused specifically on modeling and documentation activities on software development projects and one that explored what agile teams actually do in practice. Reality is definitely far from the rhetoric.

Up-Front Modeling

Dr. Dobb's 2008 Modeling and Documentation survey discovered a few interesting things about how teams approach modeling. It found that 18 percent of traditional teams did no modeling at all, compared with only 5 percent of agile teams, implying that agile teams are arguably more likely to model than traditional ones. It also found that the primary approach to modeling on agile teams was that 55 percent of teams preferred to sketch to think things through or to communicate ideas, and an additional 30 percent both sketched, then captured critical sketches when it made sense to. The majority of traditional teams also focused on sketching, with rates of 33 percent only sketching and 33 percent sketching and then capturing critical ones. Seven percent of agile teams use software-based modeling tools (SBMTs) such as ER/Win or Rational System Architect (RSA) for documentation purposes and 5 percent for full round-trip engineering, compared with 16 percent and 0 percent for traditional teams, respectively. Figure 1 summarizes the results for all four types of teams that the survey looked at: ad-hoc, traditional, iterative, and agile.

The Ambysoft 2008 Agile Practices and Principles survey explored how well agile developers agreed with various development strategies. To explore whether agile teams were doing up-front requirements modeling, it asked "We do some initial requirements modeling at the beginning of agile projects for scoping and planning purposes." The survey found that 74 percent of respondents either strongly agreed or agreed with this statement, 18 percent were neutral, and only 8 percent indicated disagreement or strong disagreement. Similarly, to explore up-front architecture modeling, it asked the question "We do some initial architecture modeling at the beginning of agile projects to get going in the right technical direction." The results were almost identical, with scores of 73 percent, 19 percent, and 8 percent, respectively. In short, two different surveys to two different communities both showed that agile development teams do, in fact, model.

[Click image to view at full size]

Figure 1: Primary strategies for modeling for various software development paradigms.

Agile teams are doing up-front modeling because they still need to answer questions around the scope that they're addressing, the relative cost and schedule, and what their technical strategy is. Without coherent answers to these questions, the project simply won't get funding. Although you need to do some modeling early in the project lifecycle, that doesn't imply that you need to write mounds of documentation to do so. You can gain the benefit of modeling, which is to communicate and think things through, without accepting the costs of unnecessary documentation.

Another reason why agile teams are doing up-front modeling, contrary to the popular belief of extremists in the agile community, is because architectural metaphors are not sufficient. System architectures are complex, addressing a myriad of nonfunctional requirements and technical constraints such as performance, security, scalability, usability, legacy assets, integration, and many more (see my October 2008 column on this topic). An architectural metaphor simply isn't going to get the job done. For example, consider the website for the Agile 2008 conference (www.agile2008.org), which was built around the metaphor that organizing a conference is just like running a stage production. This metaphor clearly didn't work well because people didn't find the website very usable. For example, to put together a schedule for yourself you needed to navigate the 19 stage pages to get detailed listings of what was being offered on each "stage." Yikes. A little bit of up-front requirements and architecture envisioning could very likely have avoided this sort of problem.

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.