The Unified Modeling Language (UML), now a world standard for almost 11 years, comes in handy in requirement elicitation and documentation of software development projects. This diagram-based "language" has become a vital complement to natural language in well thought-through specs. Why is that? Which parts of it work well in requirements? Why aren't use cases always enough? And why do the advocates of model-driven architecture (MDA) and executable UML stress its formal syntax with quite some fervor?
Let's explore the answers to those questions now.
How UML is important when talking to colleagues
An increasing number of multilingual specialists worldwide would agree that natural language carries a natural ambiguity both directly in its vocabulary and indirectly in the way we use it. (English provides many examples of this.) Standard diagrams, on the other hand, enhance communication and minimize misunderstanding, as they both set a clear overall agenda and add rigor to the details.
Standardization has minimized misinterpretation, in contrast to a multitude of ad-hoc notations and proprietary "bubbleologies" in the past. But requirement communication is a two-way street. That makes the tradeoff between rigor and stakeholder involvement an ever-changing balancing act. First, the natural owners of requirements are the stakeholders. Second, independent of ownership, an active dialog is the best form of communication, which usually translates into a lightweight approach.
Why not rely solely on use cases? In my experience, friction in many early-adopter projects, not to mention in maintenance, usually came from squeezing too much into use cases in terms of external workflow and internal processing within the system-to-be. This wasn't quite the easy street it seemed to be. For example, internal processing was usually sketched repeatedly in multiple use cases, causing either repeated effort on each upgrade or contradictions among different use case documents in new versions.
Currently, the trend toward increasing automation and decreasing user interaction poses another challenge to use cases. A slim-line UML style in requirements benefits from multi-view documentation (as opposed to one-view). Specifying each aspect once but well, showing and upgrading it at one place (and simply referencing it there) simplifies upgrades, increases flexibility and makes parts of the specification reusable. The UML diagrams that qualify for a reasonably lightweight approach are flows (BPM notation, activity diagrams), use cases (diagrams and bullet lists), classes, and in some applications (such as real-time, embedded, management games or simulators) even a number of sequences and states.
Each of these five diagrams has strengths and limitations. It is therefore vital to keep each view of the proposed system in the right diagram. Although the UML doesn't ban "borrowing" UML elements across different types of diagrams, such a compact "intermixing" style usually turns out to be a mixed blessing during upgrades.
- Flows are powerful in providing the context for use cases in applications such as back-office systems. As for the next level (use cases), where flows would in effect duplicate a bullet list describing a complex dialog, sequence diagrams from UML 2.0 and onward can provide a more maintenance-friendly alternative due mainly to their time axis.
- Use cases delimit the system-to-be and sketch external functionality: what the system shall be doing, what shall happen at the system boundary during interaction with humans and with external systems. Stretching them to depict considerably more tends to backfire in maintenance. I often use informal footnotes in use cases if there's a risk of losing some points down the road. Very useful "attachments" to a use case description are GUI-layouts and functional prototype demos. UML's use case diagrams are a flexible, semi-formal notation that makes a good graphical index of all actors, all use case bullet lists and their interrelationships. Formal rigor can be introduced a step later in sequence diagrams.
- Classes map out key business concepts, their relationships and the business rules applicable to these, that is, what the system is about. They are static in nature, depicting structure, and also are more static over time (across new versions) than the rest. They are the kernel of reusable components.
- Sequences specify the (internal) messages to be sent across the structure during a scenario (a particular execution of a use case). They provide a slightly more architectural view, whereas States describe the life cycle of an object (per class) and are useful for programmers because they depict diagrammatically the business rules that govern states and state transitions.
I usually use both diagrams because otherwise people tend to squeeze too much into either one and get bogged down in detail. Or they force-fit these aspects into use cases (that would make a "techie" menu-based use case as opposed to one that is business-event based). In the mainstream of analysis and design today, a sequence diagram ties together a chain of relatively simple state machines.
How UML is important for talking to machines
In the long run, however, it is wise for stakeholders to realize that alignment to standard in classes, sequences and states will pay off twice. First, such an alignment makes key system "blueprints" executable. In many organizations, requirements and verification are closely intertwined. Animating analysis diagrams means that their correctness and completeness of logic can be tested and verified early on, before they are translated to code. That, in turn, makes it easier to see if analysis activities in an iterative project are on schedule.
Second, if a diagram's business logic is correct and complete, then design can focus solely on fitting this logic onto a computer platform -- leveraging the code-automation opportunities of MDA and executable UML. Cutting-edge projects that use executable UML as a programming language effectively transfer today's object languages into the same category as assembler. Thus, correctness of communication between human roles pays off once again in communication with the machine.
About the author: Milan Kratochvil is an independent consultant and trainer based outside Stockholm, Sweden. He focuses on IT requirements, model-driven development and architecture in general and on variance, customization and configurability in particular. Milan is also co-author of UML Xtra Light -- How to Specify Your Software Requirements and of Growing Modular -- Mass Customization of Complex Products, Services and Software.