Dr. Dobb's is part of the Informa Tech Division of Informa PLC

This site is operated by a business or businesses owned by Informa PLC and all copyright resides with them. Informa PLC's registered office is 5 Howick Place, London SW1P 1WG. Registered in England and Wales. Number 8860726.

Channels ▼

Just Good Enough

Software Development's Agile Modeling Newsletter: December 2004

The simple definition of an agile model? It's just barely good enough. Similarly, a document is agile when it's just barely good enough. Although traditionalists may balk at this definition, agile models (and similarly agile documents) are the most effective. If a model is not yet good enough, you clearly have more work to do. If a model is more than good enough, you've invested too much time in creating it, and therefore you've wasted your stakeholder's money. When a model, or a document, is just barely good enough it's most effective.

In my experience, a model is just barely good enough when it:

  1. Fulfills its purpose. You must know why you're creating a model and ensure that it meets its goals.

  2. Is understandable to its audience. It must use a notation and/or language that its audience understands.

  3. Is sufficiently accurate. Few models need to be 100 percent accurate. If a street map is missing a street, do you throw it away? No, you don't expect it to be perfect nor do you need it to be.

  4. Is sufficiently consistent. The people who work with your models do have the ability to overcome minor challenges such as determining which information is correct.

  5. Is sufficiently detailed. Here, sufficiency depends on the audience and the reason they're using the model—drivers need maps that show streets; builders need maps that show sewers, gas lines and electrical tunnels.

  6. Provides positive value. If a model's cost outweighs its benefit, why create it? Don't spend $100,000 developing a detailed architecture model when a $5,000 investment in sketches would suffice.

  7. Is as simple as possible. With a UML class diagram, you rarely need all of the notation available to you; instead, a subset suffices. Furthermore, perhaps a simpler Class Responsibility Collaborator (CRC) model is sufficient.

Similarly, a document is just barely good enough when it:

  1. Maximizes stakeholder investment. An agile document's benefit is greater than the investment in its total cost of ownership (TCO), and ideally the investment made was the best option available for those resources.

  2. Is lean. An agile document contains just enough information to fulfill its purpose and no more. One way to keep agile documents lean is to follow pragmatic programming's DRY (Don't Repeat Yourself) principle.

  3. Fulfills a single purpose. The "one size fits all" approach typically leads to documents that contain everything but the kitchen sink.

  4. Describes information that is less likely to change. A document that contains rapidly changing information becomes out of date rapidly and therefore is difficult to maintain over time.

  5. Describes "good things to know." Agile documents capture critical information, information that isn't obvious, such as design rationale, requirements, usage procedures and operational procedures.

  6. Has a specific customer and facilitates the work efforts of that customer. Different customers require different types of documents, and very likely different writing styles. You must work closely with the customer, or potential customer, for your documentation if you want to create something that will actually meet their needs.

  7. Is sufficiently accurate, consistent and detailed. Agile documents are just like agile models in that respect.

"JBGE" Challenges
Though it's extremely effective, "just barely good enough" can present some challenges. First, sufficiency varies with the situation. A point-form use case may be just barely good enough for one project, but sadly inadequate in another. A 50-page user guide may be just barely good enough for one system, but far too much for another.

"Just barely good enough" is in the eye of the beholder. When you ask a maintenance programmer what he needs to be effective, he'll tell you that he wants concise system-overview documentation that describes the system's "landscape," a good test suite that validates the code, and high-quality source code that's easy to evolve. This is a far cry from the comprehensive system documentation demanded by the bureaucrats among us. Similarly, when you ask an end user what he needs to be effective, he'll tell you that he wants training on the system, a usable user interface, and problem-specific troubleshooting information (or, better yet, access to a knowledgeable support person). Until you know what the audience for a model or document needs, you'll never be able to develop something that actually meets those needs.

How can you create models and documents that are just barely good enough? First, adopt Agile Modeling (AM)'s "Model with a Purpose" principle. You should know why you're creating an artifact, who it's for, and how the user will work with it. If you don't understand these three factors, you're likely to record more information than you need out of fear that someone, somewhere, sometime, may need it. This leads not only to over documentation, but very likely to the unintentional repeated capture of the same information.

Second, follow the AM practice "Model with Others." Software development is a lot like swimming—dangerous to do alone. The adage is right: Two or more heads are better than one. This practice improves communication on your project, helps to build a common vocabulary among the people you're working with, increases the chance that you'll do quality work, and provides opportunities for people to learn from their coworkers.

Third, adopt the AM practice of "Active Stakeholder Participation." This is closely related to the practice "Model with Others." It is an expansion of Extreme Programming (XP)'s "On-Site Customer" practice, which describes the necessity of on-site access to people (typically users or their representatives) with the authority and ability to provide information about the system and to make pertinent and timely decisions regarding it. However, you can do better. You're not the domain expert—your project stakeholders are, doesn't it make sense that they be actively involved with modeling aspects of the domain? Of course it does. Scan take an active role when you adopt simple, inclusive modeling techniques that use simple tools.

Modeling and documentation doesn't need to be a bureaucratic and relatively ineffective activity. Streamline your efforts by creating models and documents that are just barely good enough. When you do so, you'll discover that the resulting artifacts are the most effective possible for your situation.

—Scott W. Ambler


"Extreme Programming Explained: Embrace Change (2nd Edition)" by Kent Beck and Cynthia Andres (Addison-Wesley Professional, 2004) is now in print. If you're interested in XP, this is the book for you.

The concepts behind Agile Documentation are described in detail at

Techniques for supporting active stakeholder participation on your project are described at

Inclusive modeling approaches that use simple tools and simple techniques are overviewed at

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

The principles of Agile Modeling are described at

The practices of Agile Modeling are described at

Check out the Agile Modeling mailing list at

Get agile modeling training resources 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.