Channels ▼

To Document or Not to Document

Software Development's Agile Modeling Newsletter March 2004

Welcome to Software Development magazine's Agile Modeling newsletter. This monthly e-mail newsletter is a free service for Software Development and SD Online subscribers. If you do not wish to get this newsletter, please follow the unsubscribe directions at the bottom of this message.

In This Issue:
--When Should You Document?
--Recently on the AM Mailing List
--Hot Links

The Agile Modeling (AM) methodology defines principles and practices for effective modeling and documentation. It's important to recognize that you need to create just enough documentation when developing software -- too much not only sucks the life out of the project, but also puts your project at risk for failure. Not enough documentation is also dangerous, because you won't be able to maintain and support the system effectively. In other words, you need to travel light, yet recognize that enabling the next effort (for example, maintenance, support, operations ...) is crucial for success.

So, what are valid reasons for creating documentation?

-- Your project stakeholders require it.
Creating documentation is fundamentally a business decision: You're investing your project stakeholders' resources; therefore, they should have the final say on whether their money is spent on nontechnical expenses. If they ask for a document, and understand the trade-offs involved (more on this later), you must create it.

-- To define a contract model.
Contract models define how your system and an external one interact. Some interactions are bidirectional, whereas others are unidirectional, making the interactions explicit to everyone involved. Contract models are often required when an external group controls an information resource that your system requires, such as a database, legacy application or information service. The AM practice "Formalize Contract Models" states that a contract model is something that both parties should mutually agree to, document and change over time if required.

--To support communication with an external group. It isn't always possible to colocate a development team, and it isn't always possible to have project stakeholders available at all times. When you need to work with an external group of people, you need to find ways to communicate with them. Shared documentation is often part of the solution -- along with occasional face-to-face discussions, teleconferencing, e-mail and collaborative tools -- but it should play only a supporting role. Documentation should be a last resort for communicating with an external group, because it's far too easy to misunderstand something that's been written.

-- To think something through. The act of putting your ideas down on paper can help you to solidify them and discover problems with your thinking. This, in effect, extends the AM practice "Model to Understand" into the realm of documentation. What appears clear and straightforward in your mind can often prove to be very complicated when you try to describe it in detail. For this reason, I often suggest that people write comments before they write their code -- a strategy I've followed for years.

Now let's explore very common, yet invalid, reasons for documentation:

-- The requester wants to appear to be in control. People will request documents that they can review and sign off on. Instead, ask them to provide constructive feedback about the working software that your team has built, enabling them to add real, not merely political, value.

-- The requester wants to justify his existence. Ask the requester what he intends to with do the document, why he needs it, why creating that documentation is more important than other work that your team needs to do, if there are more efficient approaches, and so on.

-- The requester doesn't know any better. Many people may not be aware that you can successfully produce software in an iterative and incremental manner without mounds of useless documentation.

-- Your process says to create the document. Although this isn't a problem with agile software processes, it can be with prescriptive processes.

-- Someone wants reassurance that everything is OK. For some reason, people think that a document indicates how well a project is going. However, working software is really the only safe measure of success.

-- You're specifying work for an internal group. Documentation is one way to communicate, but it isn't the best. Instead, consider working sessions with the other group or the use of collaborative tools.

-- Your development contracts are routinely subject to re-competition.

So what? If your primary goal is to develop software, focus on developing software. You're much more likely to perform adequately enough to keep the contract.

I think that Plato said it best: "Anyone who leaves behind him a written manual, and likewise anyone who receives it, in the belief that such writing will be clear and certain, must be exceedingly simpleminded ..." Perhaps a little harsh, but something to consider.

This newsletter has been modified from the my book Agile Modeling: Techniques for Extreme Programming and the Rational Unified Process (Wiley, 2002).

I'm pleased to announce that my new book The Object Primer 3rd Edition: Agile Model Driven Development with UML 2 is now available. Hope you like it.

Recently On the Agile Modeling Mailing List:

Are You Ready for MDA?
We discussed the main points of my previous AM newsletter and the drawbacks of the MDA vision and the tools that currently support it. The general consensus? The tools aren't there yet, some of the better tools require you to learn their proprietary action languages (although perhaps programming languages such as Java or C# would be a better choice), and the MDA community is clearly struggling with agile concepts.

Too Ambitious
One poster described his current work situation: He'd been promoting the idea of modeling to his fellow developers, most of whom were indifferent. After being assigned as architect on a new project, he broached the idea of taking a model-driven approach. Some of the advice list members offered was to take an iterative and incremental approach, to focus on people over tools, to not preach modeling, but instead mentor and coach people, and to get working software in front of stakeholders as soon as possible.

An Anecdote About Diagrams
One poster shared a story about a meeting he had with business sponsors. They walked the IT folks through a mess of a workflow diagram that they'd developed. The IT team showed the stakeholders how to draw UML activity diagrams, and after about 10 minutes of whiteboarding, the issues were resolved. The stakeholders were so impressed with the technique that they requested that the IT team train them in the technique.

Hot Links:

Various means of communication are available to software developers; this article compares and contrasts their effectiveness.

To learn more about agile documentation, visit

To learn more about UML 2 Activity diagrams, visit

Looking for training in an agile approach to applying the 13 diagrams of UML 2? If so, visit

The Agile Alliance homepage is the best starting point for anyone interested in learning more about agile software development.

With Agile Model Driven Development (AMDD) you create models that are just barely good enough to drive your implementation efforts.

Check out the Agile Modeling mailing list 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.