Modeling in Cold Blood

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


6 responses to “Modeling in Cold Blood

  1. You’re right. Modeling for conceptualization and collaboration is not documentation, any more than source code is.

  2. My advice: Always Work with a Purpose!

    Avoid the easy dichotomy between documentation and modeling: documentation is simply a kind of modeling.

    In either case, purpose comes from what you are trying to understand and convey to yourself and others.
    Using concepts of ISO/IEC 42010 (aka IEEE 1471)., the Architect is always seeking to address specific architecture concerns for specific audiences of stakeholders. The “right” abstractions (plural) follow from identifying those two ingredients.
    The “right” abstractions may vary for each: a maintainer needs a different set of abstractions to understand your system than an installer, than an operator or than the agency that must validate its implementation and certify it prior to operation.

    Agile’s “user stories” can help find a system’s functionality, but often miss the system qualities which dominate architectural considerations and concerns. “Maintenance stories” are a step in the right direction, but I advocate “stakeholder stories” from key participants: use cases, change cases, deployment cases, evolution cases, validation and certification cases, any of these may be crucial for your architecture.

    The best Architecting is always hot-blooded in every phase. The best time to “document” is when engaged with the subject matter.
    Good documentation for operators, maintainers is just as important as for the architect’s immediate audience: the developers.

    Templates or standards that get in the way of working with a purpose should be:
    1) treated with suspicion;
    2) used as checklists of things to consider or not forget about;
    3) fixed or replaced: architects who want to contribute to the growth of the field, when encountering “bad” templates and standards, take the time to comment and improve them.

  3. Hello Nanette,

    When reading your post, I got to wonder if you have ever used the UML to do any of your modeling? I don’t get a sense that you have.

    Quoting you; “When you’re modeling to solve a problem, the abstractions come naturally “. That is precisely what I find happens when I use the UML notation as a help to solve a problem. A bonus is that I end up having also documentation.

    What is more, a number of tools exist today, to name but one Enterprise Architect from SPARX, which provide “round-trip engineeering” for your UML models. this enables the developpers to update the model should they need to make any changes to it.

    By the way, in the UML community we don’t think that UML is incompatible with Agility. The two approaches can be effectively married.

  4. Hi George

    Thanks for your comments. Actually, I am familiar with UML. In fact, for a number of years I was responsible for design and implementation of a pretty sizable RUP-based SDLC initiative.

    To me, the problem is not so much whether you’re modeling using formal UML or informal UML or some idiosyncratic notation of your own devising. To me the problem is that many, if not most, architects and designers will do enough modeling to clarify their implementation approach and to communicate to their immediate team. After that, the models are often abandoned and important implementation details and inevitable changes of direction are no longer captured.

    Depending upon the size and geographical distribution of the team, this may or may not be a problem for the immediate release. However, as members begin to disperse, tacit knowledge becomes lost and the original models, which once were sufficient, are no longer adequate to bring new team members up to speed. When new team members do not adequately understand the intent of the original architecture and design, they may make costly mistakes as they go on to add features or refactor or modify quality attributes of the system.

    I have to say that I once held out a lot of hope for round-trip engineering but found myself disappointed. In my experience, many times the generated code required subsequent hand-modification and, once modified, could no longer be generated. Also, the generated models were often too busy and had to be hand-stripped to get down to the salient details.

    It could be that better round-trip tools now exist and it could also be that for certain domains, round-trip engineering is more viable than for others. Regardless, I think we still a way to go to enable automatic generation of architectural documentation since this is generally at a more abstract “ConOps” type level of communication.

    By the way, in an appendix to Alistair Cockburn’s 2nd edition of “Agile Software Development”, he includes an article by Peter Naur (of Backus Naur). The article is entitled “Programming as Theory Building”. It’s a very interesting read if you get the chance.

    Thanks for the dialog. Best Regards,

  5. Hello Nanette,

    Those are good points that you raise and certainly give one lots of food for thought.


    George Gombay

  6. Rich’s coments are totally correct — always work with a purpose, use stakeholder stories, and model “hot-blooded” in every phase.

    As was brought up in the follow-up comments, way too often the architect’s models are used as a guide and then set aside. One of the features I really like about the UML Rhapsody tool is that both the architects and developers can use the same set of models, just at a different view by simply clicking a few check boxes. This allows the documentation to be updated along the way as well as ensuring the development adheres to the architect’s intent.

    The capability exists in UML tools… the issue is that the organizational culture needs to change so that the architect’s work is built upon rather than just used as a guide.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s