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:
- Fulfills its purpose. You must know why you're creating a model
and ensure that it meets its goals.
- Is understandable to its audience. It must use a notation and/or
language that its audience understands.
- 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.
- 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.
- 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
- 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
- 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:
- 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
- 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
- Fulfills a single purpose. The "one size fits all" approach typically
leads to documents that contain everything but the kitchen sink.
- 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.
- 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.
- 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.
- Is sufficiently accurate, consistent and detailed. Agile documents are just like agile models in that respect.
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