Channels ▼

Open Source

Newsflash: Agilists Write Documentation!

Agile Modeling and Documentation Best Practices

So now that we know that agile developers are in fact modeling and writing documentation on a regular basis, it begs the question why so many myths still exist. I believe that there are three primary reasons. First, the agile community struggles to coherently describe what they do in practice. For example, if you mention up-front modeling on many popular agile mailing lists, the conversation almost instantly devolves into ranting about the evils of big design up-front (BDUF) and extraneous bureaucracy with virtually no mention of what people are actually doing. Second, many traditionalists fear agile software development approaches because they require a different skillset and often greater discipline to succeed at agile. The "new rules" around agile development are naturally scary to anyone not familiar with them or anyone who hasn't taken the opportunity to make the transition yet. Third, the lack of detailed written specifications early in the project can make it seem that agile teams aren't modeling to traditionalists who aren't familiar with Agile Model Driven Development (AMDD)-based approaches. For example, we saw in Figure 1 that agile teams are more likely to model than traditional teams, that they prefer sketching rather than creating detailed documentation using SBMTs. Differences such as this can be confusing for anyone not familiar with disciplined agile strategies.

There is a wealth of material available online about how agile development teams approach modeling and documentation. The AMDD best practices are to do some initial requirements and architecture envisioning early in the project to write executable specifications via a Test-Driven Development (TDD) approach, to single source information whenever possible, to write documentation later in the lifecycle, to promote active stakeholder participation, to implement requirements in priority order, to include modeling in iteration/sprint planning activities, to create models and documents that are just barely good enough for the situation at hand, to model storm the details on a just-in-time (JIT) basis, to sometimes model a bit ahead to explore complex requirements, and to take a multiview approach via multiple models. A description of these best practices can be found at

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.