Channels ▼


Agile Documentation Strategies

When to Document

Documentation should be created on a just-in-time (JIT) manner when you need it, and only if you need it. You should document something only when it has stabilized, otherwise you will be updating it endlessly as the situation changes. This is one of several reasons why it proves foolish to write comprehensive requirements documentation early in the system lifecycle—because your stakeholders will change their minds, usually for completely valid reasons, you discover that the investment in detailed documentation was counter-productive. The implication is that detailed documentation should be written after, or at least towards the end of, the development work. Yes, you likely need to do some very high-level modeling to think things through, but investing in detailed documentation too early is questionable at best. I present a critical examination of the big-requirements up front (BRUF) approach at

Agile Modeling (AM) advises that you should update documentation only "when it hurts". People are flexible, if the documentation isn't perfect that's okay, they can figure it out. Millions of software systems are successfully running around the world as you read this paragraph, and how many do you honestly think have perfect documentation that is up to date and fully consistent? Perhaps a handful? How many billions of dollars, if not trillions, do you think has been wasted over the decades striving to produce perfect documentation? Your goal should be to produce documentation that is good enough for the situation at hand—once it's good enough any more investment in it is clearly a waste.

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.