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.

Scott Ambler (Agile Modeling) explains, in the Software Development Magazine newsletter from december 2004.

In Scott Ambler's 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 electrical tunnels.
• 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.
• 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 those resources.
• 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.
• 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.

"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.

JBGE How-To

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, 2004