If you develop software long enough, you'll eventually run into Universal Modeling Language. This happened to me last year when we started working with our offshore vendor. UML is a diagramming standard that allows you to model software in a universal way. This could be theoretically be helpful if you were working with a bunch of developers in Bangalore, India. However, it doesn't take long to conclude that UML has some serious problems, even for simple development scenarios. The biggest problem is noted in the UML Wikipedia entry:

Although UML is a widely recognized and used standard, it has always been criticized for having imprecise semantics, which causes its interpretation to be subjective.

The last time I checked, programming was about the least subjective human activity on earth. So there's a huge disconnect. You can't even get vendors to agree what UML is, as Martin Fowler points out:

• Is it a sketch?
• Is it a blueprint?
• Is it a programming language?

Fowler appears to be positioning UML as a sort of common whiteboard notation for sketching out preliminary designs prior to coding. Given the tremendous amount of interpretation necessary to decode these diagrams, I tend to agree. Unfortunately, that distinction is lost on a lot of vendors and executives who see it as some kind of perfect, universal documentation standard. But it fails so miserably at this:

1. UML isn't bidirectional. If the UML changes, the code doesn't magically write itself. And if the code changes, the UML documents don't magically update themselves either. So you end up violating the Don't Repeat Yourself rule.
2. UML can't capture many of the high-level details necessary to build software. For example, there's no way to represent Properties, or Static members. You end up looking at the code anyway because the UML is so imprecise-- even at the highest architectural level.
3. UML offers no significant advantage over other forms of documentation. In fact, UML diagrams are typically worse than other documentation. I find it much easier to read a typical all-text requirements document than a mish-mash of lines, arrows, and primitive looking stick figures.

I liked the Pragmatic Programmer take on UML:

Workflow can be captured with UML activity diagrams, and conceptual-level class diagrams can sometimes be useful for modeling the business at hand. But true use cases are textual descriptions, with a hierarchy and cross-links. Use cases can contain hyperlinks to other use cases, and they can be nested within each other.

It seems incredible to us that anyone would seriously consider documenting information this dense using only simplistic stick people such as Figure 7.3. Don't be a slave to any notation; use whatever method best communicates the requirements with your audience.

Microsoft's "whitehorse" diagramming tools in Visual Studio 2005-- which you can see visually depicted in the new ClassDesigner WebLog-- clearly arrived at the same conclusion.