Channels ▼

Embedded Systems

Agile Documentation Strategies

Scott is a DDJ Senior Contributing Editor and author of numerous IT books. He can be contacted at scottAmbler.html.

Documentation is an important part of every system, regardless of the paradigm followed to develop that system. Although agilists are sometimes maligned for what is perceived to be their cavalier attitude towards documentation, the fact is that we take documentation very seriously. Agilists adhere to the philosophy that your team's primary goal is to develop software, a message that sometime drowns out its sister philosophy that a project team's secondary goal is to enable the next effort. Because the "next effort" typically involves running, supporting, operating, and maintaining the system, chances are incredibly good that you're going to need to write some documentation along the way. It's possible to do so in an agile manner, and this month, I explore strategies for doing exactly this.

For some reason, the agile community seems to struggle to describe how we approach documentation. There are several explanations for this. First, the majority of agile developers prefer to focus on technical practices (such as regression testing, refactoring, and continuous integration) instead of "softer" practices (such as modeling, documentation, and governance). Hence, we talk about those things a lot more. Second, because the agile community is growing quickly, we have large numbers of novices who are in the early stages of learning—in their exuberance, they are all too eager to share their misperceptions with others, and a common misperception is that agilists don't document. Third, modeling and documentation practices weren't explicit in most first-generation agile methodologies, unlike second generation agile methods such as Open Unified Process (OpenUP) and Microsoft Solutions Framework (MSF) for Agile.

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.