Channels ▼


Agile Documentation Strategies

A Few Myths and Misconceptions

To understand the agile approach to documentation, you must first understand the potential misunderstandings about documentation that have seeped into traditional thinking:

  • Documentation isn't the primary issue—communication is. For example, your primary goal isn't to document requirements, it's to understand them so that you can implement them fully. Your primary goal isn't to document the architecture, it's to formulate a viable one that meets the long-term needs of your stakeholders. This isn't to say that you won't decide to invest in such documentation, but that isn't the raison d'tre for your project.
  • Comprehensive documentation does not ensure project success. Just because you have a detailed requirements specification that has been reviewed and signed off, that doesn't mean that the development team will read it, or if they do, that they will understand it, or if they do, that they will choose to work to the specification. Even when the "right thing" happens, comprehensive documentation still puts the project at risk because of the perceived need to keep the documentation up-to-date and consistent. Your real goal should be to create just enough documentation for the situation at hand; more on this later.
  • Documentation doesn't need to be perfect. People are flexible, they don't need perfect documentation. Furthermore, no matter how hard you work, it's very unlikely that you could create perfect documentation—even if you could, it isn't guaranteed that the readers will understand it anyway.
  • Few people actually want comprehensive documentation. When was the last time you met a maintenance programmer who trusted the system documentation that they were provided? Or an end-user who wanted to sit down and pore over a massive user manual? What people typically want is well-written, concise documentation describing a high-quality system, so why not invest your time to deliver that instead?
  • Documentation doesn't need to be standardized. Many organizations have adopted the unfortunate philosophy that repeatable processes lead to success, yet in reality what you really want is repeatable results (that is, the delivery of a high-quality system). The quest for repeatability often leads to templates, and because each system has its own unique set of issues, these templates have a tendency to grow over time into all inclusive monstrosities that do little more than justify bureaucracy. Try to achieve a reasonable level of consistency, but don't go overboard doing so.

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.