Monday, December 01, 2008

Irrational Artifact Attachment

The lowly whiteboard is one of my favorite tools for design work on projects: you can stand in front of it as a group, you can easily play "what-if" games with emergent designs, and you can argue until everyone agrees (or at least until everyone is equally unhappy). Once you've got it done, a quick snap with a digital camera and you've got a project artifact, ready to post on a wiki or similar until supplantation by actual code. Once you have real code, you are better off allowing the design to continue to emerge from it rather than trying to keep the two in sync. Alternatively, you can use a reverse engineering tool to produce a prettier version of the original diagram from the code.

I prefer this low-tech approach to the more formalized version using tools (from drawing tools all the way up to really formal tools like Rational Rose) because of the proportional relationship between a person's irrational attachment to some artifact to how long it took to produce. If you create a beautiful UML diagram using some tool like Visio that takes 2 hours, you have an irrational attachment to that artifact that's roughly proportional to the amount of time invested. That means that you'll be more attached to a 4 hour diagram than a 2 hour one. By "irrational attachment", I mean that it's harder to listen to reason as to why it's wrong because you know how much time it took to create it (and therefore the required effort to update it).

This applies to pretty much any software artifact. I've seen this effect for design documents and diagrams, architecture, requirements, use cases, and database schemas. This suggests that really elaborate tools favor one-shot designs, where the pressure is on to get it right on the first pass. Of course, you can change it, but how much willpower exists to do that? One of the benefits to the low-ritual approach to much of agile software development revolves around creating "just in time" artifacts, with as little ceremony as possible (this helps explain the dedication to lots of agilists to index cards and sticky notes). Using low-tech tools frees you to throw away what's not right, freeing you to experiment and allow the true nature of the artifact emerge through revision, collaboration, and discussion.

9 comments:

dpattinson said...

This principle applies in spades to project plans. It's probably the biggest reason that MS Project and other 'high maintenance' tools end up being worse than useless.

Studman said...

if only you can get CTO's to understand this concept when they are so stuck in the past and have minions who love to design but never have to implement.

Jim Shingler said...

Studman, I appreciate the points you bring up. The fact is that we operate within a larger world, and the documentation gives them a sense of security. Traditionally, it is how they got a sense of progress.

I think the trick is too satisfy the demands of the environment in the most productive manner possible. Let's not confuse the means and end.

The goal is a functioning solutions and the appropriate support artifacts. Not necessarily reams of shelfware.

So, we can use techniques like whiteboards and cameras as a productivity tool and if it really that important, we can come back and refactor the documentation with pretty visio diagrams as appropriate.

Jim Shingler said...

Studman, I appreciate the points you bring up. The fact is that we operate within a larger world, and the documentation gives them a sense of security. Traditionally, it is how they got a sense of progress.

I think the trick is too satisfy the demands of the environment in the most productive manner possible. Let's not confuse the means and end.

The goal is a functioning solutions and the appropriate support artifacts. Not necessarily reams of shelfware.

So, we can use techniques like whiteboards and cameras as a productivity tool and if it really that important, we can come back and refactor the documentation with pretty visio diagrams as appropriate.

Morgan Creighton said...

We recently put a couple of hand-drawn diagrams into a formal design document. This was a non-customer-facing document for engineers. We drew on graph paper with craft store stencils and scanned them. Originally, we planned to redo them in Visio in time for the review, but then thought, well, let's wait and see who complains.

Turns out, we made it through many reviews, during which time the diagrams were tweaked over and over collaboratively. It was trivial to redraw them and scan in the improvements. Nobody ever even mentioned that we didn't use Visio.

You know the punchline. At the very last minute after all the signatures for approval were gathered, a manager who never participated in any of the reviews held up the doc because two of the diagrams were not done in Visio.

The result was not an irrational attachment on our part, but an irrational resentment. There is an unaccounted-for cost of frustrating the developers, and it took us a little while to get back on our game. The temptation was strong to project the Visio diagrams onto a wall and then snap a digital photo, but we didn't succumb.

I echo what Jim wrote and I feel that he's absolutely right. Artifacts are essential. There are many occasions when refactoring the documentation makes a lot of business sense.

But marginally competent managers sometimes ask for busy work that adds no business value. That robs precious time from me that I'd rather be spending with my three year old.

Jim Shingler said...

Morgan, LOL you said it. :-))))

Itay Maman said...

An excellent point.

I don't like tools that force me to formalize my thoughts ("you can't draw this arrow here", "you need to change this shape", etc.). They make the (false) promise that it will be easier to develop the code once the diagram follows some formal notation (e.g.: UML).

In reality, the notation is so formal that the drawing itself becomes an act of programming. Which means that we just move the difficult part from here to there.

Yanic said...

Hi,

I hadn't heard of the irrational attachment argument, interesting perspective. I've never had the impression that anyone defended a suboptimal design because of the effort that went into drawing diagrams for it, it does seem plausible, but I've certainly seen people become emotionally attached to their ideas :o)

About the whiteboarding technique you describe, then photographing it and afterwards generating it again from code, I think you're mainly talking about static structure and class diagrams?

When it comes to system dynamics and sequence diagrams, I think a tool like Trace Modeler opens some interesting possibilities (disclaimer : I'm the author).

Because it is so easy and fast to work with sequence diagrams, I believe it is well suited for the collaborative discussion and prototyping of system dynamics. It certainly faster than any other technique/tool I've seen.

Basically, one person is using the pc (with beamer) and draws the ideas/alternatives the team members are discussing. You could even pass a cordless mouse around, but I believe it is faster with one 'dedicated' operator.

It also allows for the generation of sequence diagrams from code with defined filters to give the resulting diagram focus (work-in progress and nearing beta stage, but java only at this time).

I think it is a worthwhile extension to the pragmatic approach you describe, but it depends entirely on having a tool that's as fast to work with as Trace Modeler.

I've used it many times in a class room setting to present and prototype design ideas, including quickly prototyping alternatives offered by the audience. I don't see why it wouldn't work in the kind of setting you describe.

I would really love the hear your opinion on this, perhaps you're willing to give it a try the next time you're having such a design meeting? I'd certainly be willing to sponsor your attempts with the necessary licenses.

Best regards,
Yanic

PS : it can also export to vector formats (svg, eps, etc) and high dpi bitmaps, should prove useful for an author.

David Dossot said...

With yUML making a diagram no more expensive than an HTTP GET, maybe the irrational attachment will vanish?