Dr. Dobb's | Tools and Evidence

Tools and Evidence

Within IT organizations, modeling and documentation are often associated with dysfunctional practices that provide little value beyond employing those people who perform them. This waste frustrates many developers, providing motivation to seek more efficient ways of working-hence, the popularity of agile approaches. Unfortunately, many pro-agile developers are also antimodeling, anti-analyst, antidocumentation, anti-architect and anti anything remotely associated with these practices. In reality, modeling and documentation are vital to software development, even in agile software processes such as Scrum, Dynamic System Development Method and yes, Extreme Programming. Modeling and documentation can be quite effective, but you may need to rethink your approach to make them so.

May 01, 2002
URL:http://www.drdobbs.com/tools-and-evidence/184414853

May 2002: Tools and Evidence

Within IT organizations, modeling and documentation are often associated with dysfunctional practices that provide little value beyond employing those people who perform them. This waste frustrates many developers, providing motivation to seek more efficient ways of working—hence, the popularity of agile approaches. Unfortunately, many pro-agile developers are also antimodeling, anti-analyst, antidocumentation, anti-architect and anti anything remotely associated with these practices. In reality, modeling and documentation are vital to software development, even in agile software processes such as Scrum, Dynamic System Development Method and yes, Extreme Programming. Modeling and documentation can be quite effective, but you may need to rethink your approach to make them so.

Documents and Models

A document is any artifact external to source code whose purpose is to convey information in a persistent manner; documentation includes both documents and comments in source code. A model is an abstraction that describes one or more aspects of a problem or a potential solution addressing a problem. Some models will become documents, or be included as a part of documentation, while many more will be discarded once they've fulfilled their purpose.

Identity Crisis
Let's start by reviewing the relationships between models, documents, source code and documentation, which are depicted in the UML class diagram, "Documents and Models." A document is any artifact external to source code whose purpose is to convey information in a persistent manner; documentation includes both documents and comments in source code. A model is an abstraction that describes one or more aspects of a problem or a potential solution. Some models will become documents, or be included as a part of documentation, while many more will be discarded once they've fulfilled their purpose. Some models will be used to develop source code, while others may be used to develop other models.

Models aren't always documents. For example, a whiteboard sketch of a UML activity diagram is clearly a model, one that you may draw to analyze a user requirement but then erase once you're finished with it. Similarly, documents aren't always models; for example, I wouldn't consider a user manual to be a model. This insight is important because many developers automatically translate model into document—replete with all the negative connotations that word implies. Carefully repeat after me, please: Models are not necessarily documents; models are not necessarily documents; models are not necessarily documents! The concepts of "model" and "document" are orthogonal, because you can clearly have one without the other.

From Temp to Perm
Models can be temporary for two basic reasons: First, once a model serves its

purpose and no longer adds value, it should be discarded. Second, many models are superseded by other artifacts such as other models, source code or test cases that represent the information more effectively.

Some models evolve to become part of your system's permanent documentation, but how do you make this evolution agile?

Agile models begin as an idea—"We need to understand how we're going to build this" or "How do the users want this to work?"—that you may choose to model or to abandon (any nonmodeling activity you choose to perform counts as "modeling abandonment"). All agile models start out temporary, often as hand-drawn sketches created to help you understand something about your system or to communicate your approach to others. These sketches are discarded once they've fulfilled their purpose. You'll naturally update temporary models as required, often creating and working on them over a short period of time: Many agile models are produced in several minutes by two or three people to facilitate discussion, whereas other agile models are created during modeling sessions that include a larger group of people over a period of several hours or days.

Even "temporary" models can be long-lived: Often, development teams draw system architecture diagrams on a shared whiteboard and leave them there for weeks, evolving the diagrams over time as they explore ideas about building the system.

Evolution of a Model

This UML statechart depicts an interesting transition, one that occurs when you decide to keep a temporary model, making it a permanent addition to your project team's official documentation.

"Evolution of a Model" depicts the transition that occurs when you decide to make a temporary model a permanent addition to your project team's official documentation. Your model becomes a "keeper" when it meets all of the following criteria:

There is a clear and valid reason to make it permanent.
There is an audience for which the document provides value.
Your project stakeholders are willing to invest in evolving your model into a document.

Crucially, the people paying the bills must understand all of the costs of documentation, both overt and hidden (including maintenance and lost opportunities to provide additional system functionality instead of documentation), as well as the potential benefits of creating the document. When you start actively questioning each document's creation, you quickly discover that you need far less documentation than you think.

Tool Use
To become increasingly agile, you must rethink your toolset. If most models are temporary, you probably don't need to capture them in a CASE tool. And, because each model or document must provide value, your CASE tool must do more than draw pretty pictures. Agile modelers typically start by discussing an issue. If that discussion is sufficient, they can start writing code. At other times, realizing that they need to model, they choose the simplest tool possible to get the job done. Index cards, whiteboards or sticky notes will often suffice, although sometimes the job will require a sophisticated CASE tool capable of generating and possibly reverse-engineering source code. Regardless of the tool employed, agile developers may produce code at any time, because agility demands an iterative and incremental approach to development.

In a project's early stages, a very flexible tool can effect rapid changes to a model; because much initial work is likely to be discarded as understanding evolves, time is at a premium. For example, when I first explore the design of Java software, I'll either create several Class Responsibility Collaborator cards or simply draw a UML class diagram on a whiteboard. Both tools are inclusive, making it easier to obtain input from other developers, and enable rapid model evolution as discussion progresses. Once I'm happy with my design, I may migrate it into a CASE tool. I'll use each tool for what it's good at—simple tools for supporting communication, and complex tools for "hard-core" development.

Agile is Possible
When you hear the terms modeling and documentation, is your first reaction a fist-pumping "Yes!" or an eyebrow-raising "No"? In either case, you're probably part of the problem. In these extreme reactions, the fist-pumpers tend to denigrate modeling and documentation as bureaucratic activities that hamper software developers, and the naysayers tend to produce systems that are brittle and costly to maintain over the long term. Agile developers recognize that documentation and efficiency aren't mutually exclusive: You can enhance your system, while producing sufficient artifacts to support it once it's in production.