The Post-it® Notes Test for UML Diagrams 8
A lot of teams require their developers to document their designs in UML, using Visio or another tool, before they can start coding.
Of course, this is not at all Agile. For one thing, the design is likely to change quite a bit as you learn while coding. Hardly anyone returns to the diagrams and updates them. Now they are lies, because they make claims about the designs that aren’t true.
UML still has a place in agile projects, of course. It’s a great tool for brainstorming design ideas. So, how do you decide when a diagram is worth keeping and therefore, worth maintaining? Here’s a little strategy that I recommend.
Draw the diagram during those brainstorming sessions on a white board or a poster-sized Post-it® Note. Drawing it this way means you have invested almost no additional effort, beyond the brainstorming itself, to create the diagram. Also, you won’t feel bad about lost work if you eventually throw it away.
Leave the diagram on the wall for everyone to see while they implement the design.
By the time the note is falling off the wall or the dry-erase marker is wearing off the white board, you’ll know if the ideas are still relevant or completely obsolete.
If they are obsolete, you can erase the board or toss the paper. If they are still relevant, and probably changed somewhat, you now know that the diagram is worth preserving. Go ahead and spend the time to create an updated, more permanent version in your drawing tool (but don’t spend too much time!).
Great post Dean. One other way to try to meet this “diagram first” criteria (particularly with distributed teams where a poster / whiteboard may not work) is to get your team a cheap digital camera. When you are done brainstorming, take a photo and use the photo in your documentation wherever the traditional Visio diagram would be typically be used. If you need to edit the diagram, reproduce it on a whiteboard and take another photo. If a more permanent record is required, then as you mention, you can take the time in the traditional tool. Often however, you’ll find that the people insisting on the Visio / UML have their requirements satisfied when they see the photo in the document.
Very good post. I have always found it difficult to be agile and maintaining some diagrams with so little of time spent on analysis.
Hi Dean,
That sounds like a good filter, hope you have plenty of wall space ;o)
But seriously, the problem would be a lot smaller if tool vendors did a better job from a usability perspective. Something is seriously wrong if people can draw their diagrams faster on paper than with computer support.
At least when it comes to UML sequence diagrams I think I’ve created something that fits well with the agile mindset : Trace Modeler, an easy to use and smart editor for UML sequence diagrams.
It makes it really painless to draw and change sequence diagrams and is much faster than anything you could do on paper. Basically it takes care of all the layout issues, freeing you to focus on the content.
You can check out a 30 sec demo on the download page at http://www.tracemodeler.com/download/index.html
Once updating a diagram becomes quick & painless, I believe the equation for agile documentation alters. And even if it doesn’t, you’ll have saved some time anyway!
If you give it a try, let me know what you think of it. I’m always happy to get feedback of course, but I’m especially interested in how Trace Modeler can better support ‘agility’.
Best regards, Yanic
“A lot of teams require their developers to document their designs in UML, using Visio or another tool, before they can start coding.
Of course, this is not at all Agile.”
Huh? Why is this not agile? The real requirement here is that there should be a minimum design done before coding. Would you start building anything of remote complexity without a plan? You want at way to promote conceptual integrity throughout the lifetime of the application.
I think your issue is the requirement to use Visio. However, if the team wants to use Visio, and is empowered to do so, is it not “agile”? As long as the expectation is made to keep it up-to-date and the team understands that I don’t see an issue here.
@Aaron, In my experience, I start with a design in mind, of course, but it quickly evolves as a drive it through TDD. I rarely find that my “initial plan survives contact with the enemy”, to paraphrase Helmuth von Moltke the Elder. TDD is not only an implementation approach, it is also a process of discovering the optimal design.
We all form conceptual models as we go. Sometimes it’s useful to capture some of the big-picture ideas graphically, but I rarely find it useful to go beyond the “Post-It Note” approach.
Again, I assert that drawing lots of design diagrams in Visio or any other (maybe faster) tool is not agile. It’s not code. It doesn’t execute. It’s only when you write executing code that you discover the optimal design, if you’re not constrained by a design that you’ve invested in and you feel bound to uphold. That’s perhaps the most pernicious problem with Big Designs Up Front, not the sub-optimal effort, but the pressure to stay true to the design, even when your implementation is driving you in a different direction.
I say this as someone who believed very strongly in modeling a decade ago, when it was considered the state of the art, and who even worked for a time at a Well-Known Company That Promotes Modeling. We’ve learned a lot since then.
@Yanic, I’ll have to try TraceModeler. Indeed, when I worked on modeling tools for the WKCTPM ;), I realized pretty quickly how inefficient our tools were, compared to a good text editor, and how much they needed a good human-factors makeover!
@Paddy, thanks for mentioning the idea of using a digital camera. It’s a very good solution for distributed teams and which teams aren’t distributed these days??
While UML seems like a fine because it is a standard and therefore it evicts the diagramming mess that existed before UML, UML still lacks several qualities that I would like to have in a design tool.
Most of the time when I’m speaking about the design of a class library, I draw a triangle meaning “all the descendants of this class”. There is no way to say that in UML.
Also, UML can’t capture design patterns in any meaningful way. I can’t even think of having design meetings and not being able to draw what we say and say what we draw. UML is useless in this context.
Neither can my cellphone, but that doesn’t mean I can’t use it to communicate at all.
It’s just a notation, use it to your advantage for the things it can do and use your imagination for the rest.
Dean, I’ve made a translation of your tip to brasilian portuguese: http://expressocapital.blogspot.com/2008/02/o-teste-do-post-it-para-diagramas-uml.html
Let me know if there is any problem, or anything else.