I’ve been thinking about the issue of modeling and documentation. While many within the Agile community embrace the concept of “modeling with a purpose,” there is also a widespread view of documentation as an after-the-fact, template-based activity that generates unused shelfware. To me, this dichotomy can best be expressed as the difference between acting “in the heat of passion” and acting “in cold blood.”
When you’re trying to solve a problem, modeling is performed “in the heat of passion.” It’s done with a purpose; it’s done in a state of flow. The model that you draw represents just enough of the system to facilitate reasoning about the problem at hand.
When you’re working to document a problem that you’ve already solved, you’re modeling “in cold blood.” Many times the documentation is being recorded via templates or standards. In a lot of ways, templates and standards are very useful. They provide guidelines to constructing abstractions and prod the writer / modeler to consider a range of models and information for inclusion into the documentation. At the organizational level, standards and templates can facilitate exchange of information across different teams.
However, templates and standards can also have a mind-numbing effect sometimes. They can end up being “filled out” like a DMV form instead of being used to communicate a decision or concept or point that someone wants to convey. Let’s face it, no one thinks about communicating when they’re filling out a Department of Motor Vehicles form. You just want to finish up and get on out of there.
One piece of the puzzle, I think, is grappling with the issue of abstraction with respect to documentation. When you’re modeling to solve a problem, the abstractions come naturally (i.e., – you abstract enough information about the system to solve the problem at hand). When you’re doing so in cold blood, the question of what to abstract out about the system becomes, as it were, a little too abstract.
I’m not sure exactly what the answer is to the documentation issue. I don’t think tacit knowledge is enough. I’m not sure whether a collection of models created “in the heat of passion” is superior or inferior to a more comprehensive and orderly set of models constructed in “cold blood,” when it comes to conveying information to maintenance teams.
Maybe one potential solution would be for Agile teams to create “maintenance stories” as part of their sprint or iteration retrospectives. These stories could be enhanced or refactored across subsequent iterations. Maybe this approach could bring more of a team dynamic and sense of purpose to creating maintenance documentation. Perhaps it could increase the temperature of the documentation activity up to “warm-blooded” at least.
Nanette Brown – SEI