 | Level: Intermediate Benjamin Lieberman, Ph.D., Principal Software Architect, BioLogic Software Consulting, LLC
20 Mar 2007 Effective models communicate information accurately and efficiently to a specific audience. Unified Modeling Language (UML) models face a particular challenge because of their diverse audience, which can include developers, business owners, analysts, testers, and project managers. UML models that follow best practices feature views that are directed toward a specific form, have a common theme across all diagrams, and contain a pivot around which each diagram is focused. In this article, you'll learn how to organize and present UML model views based on the principles of form, theme, and pivot.
Introduction
Visual modeling has long been considered one of the key best practices for software development. Diagrams allow designers and analysts to more readily and effectively present complex information to a diverse audience. Unfortunately, many models are poorly constructed, disorganized, and under utilized. To gain the maximum benefit from visual model presentation, you should consider not only the content of the model, but also the presentation of the information. When creating effective system models, you need to focus on three main concepts: selection of a diagram form, organization of the diagrams around a common theme, and the creation of views focused on a specific characteristic of information called a pivot.
|
IEEE 1471: System model
viewpoints
The Institute of Electrical and Electronics Engineers (IEEE) standards body accepted specification 1471 in 2004 to describe architectural models for software-intensive systems. This standard defined the term viewpoint as a specific collection of model elements directed toward the needs of a specific system stakeholder. The standard doesn't list specific viewpoints, but it does present a technique for documenting a viewpoint stakeholder. This approach includes the name of the viewpoint, the targeted stakeholder groups, the model contents, and the presentation forms for each defined viewpoint in the model. For more information on viewpoints, review the standard IEEE 1471 or check out a Wikipedia entry on this topic. |
|
Model
forms
There are two interrelated model forms: the representational form and the organizational form. A common representational form in software development is UML, which details the specific notation and semantics for a collection of 13 diagram types, each targeted at a specific aspect of software system
development from requirements to deployment. These
include structural diagrams, such as class, object, and deployment, and
behavioral diagrams, such as sequence, activity, and state. The sheer size of such a
diagram collection means you must thoroughly understand each form,
carefully consider the intended audience, and spend time crafting a
collection of consistent and cohesive diagrams that convey the intended
purpose of the model. For example, a system designer is interested in the
logical and physical aspects of a system, so the most useful forms are class
and sequence diagrams rather than use-case and activity diagrams. By
contrast, a system analyst is interested in the functionality
described in the use-case diagram and less interested in the details of
construction and deployment. UML semantics enforce
specific modeling relationships. For example, a message relationship can only
occur between two instances of objects.
Quite a few other modeling forms besides UML are often adopted for
software modeling, including the Department of Defense Architecture
Framework (DODAF), The Open Group Architecture Framework (TOGAF), and the
Zachman Framework. (See Resources for more information on the Zachman Framework.) Different languages are also
available, such as the Integrated Computer-Aided Manufacturing (ICAM) definition language, entity-relationship
data models, and system models captured in Systems Modeling Language (SysML). Regardless of the modeling form or language you use, you must have a consistent way to describe the system of interest.
You can capture the organizational form of a model as a group of
viewpoints (see the
sidebar). A viewpoint is defined as a collection
of model views that are represented by a collection of diagrams, documents,
and other related artifacts. You create each viewpoint to satisfy a
particular stakeholder interested in the model content (see Figure 1).
Figure 1. Application
model viewpoints
See a larger version of this image.
Software applications must satisfy a diverse set of stakeholder needs, and
consequently, the models describing these systems must likewise be
complex. For example, business stakeholders are interested in the
Requirements viewpoint, which you can use to organize use-case
diagrams, activity diagrams, and other information about the system
features. Many possible viewpoints exist for a software system,
including the classic 4+1 views from Philippe Kruchten (learn more in the Resources section), as well as ones that focus on environmental
considerations, maintenance, and automated tests. Table 1 describes a
standard collection of viewpoints that should be useful to any software
system model.
Table 1. Common useful viewpoints
| Viewpoint | Viewpoint elements | Usage guideline |
|---|
| Requirements | Use cases, supplemental requirements, business rules | Contains a description of the stakeholder needs, system features,
and requirements |
|---|
| Deployment | Deployment environment and packaging | Contains the system deployment views that illustrate the
deployment into development, testing, user acceptance, and
production, and details configuration information for each
deployment |
|---|
| Environment | Server maps, network maps, system distribution | The working environment for the software, including allocation
to various system components |
|---|
| Code | Component descriptions, communications/messaging, physical
packaging | Contains the implementation details for all code-based
development, including file-system structure, build
dependencies, and configuration parameters |
|---|
| Logical | System behavior, system structure, data models, architectural
layers, design patterns | Details the full logical view of the application, including data,
behavior, and structure (such as architectural layers and
patterns) |
|---|
| Maintenance | Monitoring, alarm, reporting/logging, recovery | Reserved for operational details of the systems,
such as reporting, monitoring, logging, and recovery
procedures |
|---|
| Test | Unit test cases, automation | Supports full-spectrum testing, including unit, integration,
system, and regression testing |
|---|
Model
themes
After you decide on an appropriate form for your model, you need to organize your information according to the theme of each of
the system architectural areas. For example, a critical aspect of all
software systems is the organization of internal dependencies; one way to
express these relationships is with a layered architecture. The theme for
the collection of model views that represents this area is dependency
management. So, the model themes are governed by the nature of the system,
including the system purpose and goals. The contents of the viewpoints in a
model are gathered around particular themes, as Table 2 demonstrates.
Table 2. Application model
themes
| Theme | Description | Example |
|---|
| Layering | Dependency management | Data access layer |
|---|
| Business category | Stable business operations and
processes | Contract negotiation |
|---|
| Integration | Adapters, connectors, and interfaces
between subsystems and components | Third-party relational database |
|---|
| Workflows | System operations and control of
execution | Rules engine |
|---|
| Rules | Constraints on the system
behavior | Data validation |
|---|
| Environment | Operation systems, resources, and
configurations | Server process allocation |
|---|
| Build, package, and deliver | System components, physical
delivery mediums, and mechanics | Build files (.zip and
.tar files, FTP delivery, and HTTP downloads) |
|---|
To illustrate, let's consider one specific viewpoint and the themes
present in that viewpoint. For example, assume the system under consideration is a
scheduling application for a plumbing-repair company. The company needs to
efficiently assign routes to each truck and technician so that the technician travels
the least distance between successive job sites. A number of
stakeholders have an interest in this system, including the business owners, system developers, technicians, system administrators, data-management personnel, requirements
engineers, testers, and architects. Specific viewpoints address each stakeholder's needs. For example, the Use Case viewpoint allows the requirements engineers and business owners to discuss the features of the system functionality. The Logical viewpoint features both
structural and behavioral aspects. The structural aspect can have a number of
themes, one of which is the idea of resource scheduling. In this case, the
resources of interest are technicians, trucks, and jobs that need to be
scheduled. Figure 2 shows one such structural view.
Figure 2. Job and schedule
management
Figure 2 also illustrates how a diagram uses a pivot (discussed in the Diagram pivots section) to
present the model information. The pivot here is the structural
relationships of the JobSchedule component. In particular,
the ScheduleManager is called to the viewer's attention because of the
difference in coloration and the upper-central placement of the diagram
element. Note that the diagram shows no extraneous information, such as debug
logging. This ensures that a single message is conveyed -- the
message embodied by the diagram pivot.
In addition to the structural diagram, several other diagrams
may illustrate behavior, such as sequence diagrams and state
diagrams (see Figure 3).
Figure 3. Job state
chart
All of these diagrams share the common theme of "resource scheduling" and are
grouped accordingly in the model. By grouping model views by theme, you ensure that the model presents a
collection of organized views that are directed toward a particular
viewer (for example, a stakeholder) and represent a cohesive area of the system
description.
Diagram
pivots
Finally, you must consider the content of each specific
diagram. To ensure that each diagram presents its information
effectively, you need to ensure that the diagram contents are based
on a single, particular piece of information. The pivot provides a focus
for the diagram's elements, and it ensures that only relevant information
is included on a particular diagram. For example, in the state diagram for
Job shown in Figure 3, there is no mention of another state object; the diagram focuses solely on Job and its state transitions. If another object had
been included, the diagram would be blurred in its focus and message.
The most important point to keep in mind is this: Use the diagram to communicate model contents to viewers. Everything else is organization structure to aid in finding the said diagram in the first place.
Consequently, if the viewer is confused by the diagram message, perhaps
because there are too many messages, then it's unlikely the diagram
will have the intended impact.
People who create diagrams of complex systems have an odd tendency to
continue to add more and more information to the diagram, to the point where
the audience is completely overloaded. Perhaps they intend to create a
single view that covers all of the interesting parts of the system. However, by
presenting so much information in one visual image, the core message is lost
in the details. I've seen this many times, but one particular example comes
to mind from early in my scientific career. I was attending a seminar from a
well-known researcher who was presenting his work on cell-signaling
pathways. He started off well, with a few overview slides that each featured a single
information point -- a clean pivot for each display. Then he
presented his data on four complex graphs squeezed into a single slide. The
text was unreadable for anyone seated more than two feet from the screen; even he had trouble distinguishing each axis label. The myriad of lines
were all monochrome and meandered across each graph in a seemingly random
manner, and the data points were indistinguishable from specks of dust.
Nevertheless, this highly respected scientist spent the next 20 minutes
explaining the data shown on this single slide. Taking a look around the
room, I saw that nearly everyone (including myself) was confused, and most had
completely lost interest.
The point of this story is that it's easy to get lost in the details of the
presentation. If the presenter had simply broken the four graphs into
separate slides, everyone would have been able to see the details. Moreover, this would have created an opportunity to separate the
displays so that they dealt with only one point at a time -- a clean pivot. It
would have been simple for the audience to follow the four graphs, and a single summary
slide would have brought it all together again.
When thinking about each diagram's pivot, first consider
the presentation (or model) as a whole. What is the full system story
being told? How would this story best be presented so that each component gives
sufficient detail? What should be left out so viewers can better focus on the important
aspects? These kinds of questions lead to a good selection of
pivot points. As with forms and themes, you can choose from many
possible diagram pivots (see Table 3).
Table 3. Diagram pivot
categories
| Pivot | Description | Example |
|---|
| Control point | Centralized business-logic point | Enterprise JavaBeans (EJB) session object |
|---|
| Framework utilization | Framework elements implementation and integration | Transaction management and security |
|---|
| Risk | High complexity, coupling, and change | Architecturally relevant use-case realization |
|---|
| Architecture | Architecturally relevant use cases or system components | Architectural mechanism realization, such as messaging,
security, and auditing |
|---|
| Interface | Realization of interface touch points between subsystems and
components | Commercial off-the-shelf (COTS) integration adapters |
|---|
| Feature assignment | Traceability between requirements and design | Collaboration diagram with use-case realization |
|---|
| Performance | Focus on processing choke points, resource utilization, and
throttling | Web service |
|---|
| Structure | Structural system aspects, such as containment hierarchy, state
charts, and component relationships (dependencies) | Class/component diagram |
|---|
| Behavior | Behavioral system aspects, such as messaging, object
creation/destruction, method calls, and broadcast/listener | Sequence diagram |
|---|
In UML, each diagram focuses on a particular system aspect, such as class
diagrams that capture structural information. However, only one information focal point (that is, the
pivot) should exist within a particular
diagram type. A poorly defined pivot can muddle a diagram's
message.
Summary
Creating a system model represents a significant effort in terms of time and
money; allowing this important resource to fall into disuse due to a poorly
conceived model structure is both wasteful and counterproductive. Models
are intended to be reusable; there's no reason to spend a development team's
valuable time on building a complex, detailed, but ultimately disposable
artifact. To justify the cost of model creation and maintenance, you need to ensure that your model is highly useful.
| |
There's little value in creating complex system models
unless the information they contain is effectively organized to
allow ease of maintenance coupled with rapid discovery of relevant
information by the model audience. A disorganized model will rapidly
become inaccurate, and perhaps more important, will be difficult to use,
leading to eventual abandonment. Creating a model that features consistent form,
is organized around common understandable themes, and offers
a cohesive set of informative diagrams increase the likelihood of its
short- and long-term value. Only then will the effort expended on visual modeling be
rewarded with immense benefits.
Resources Learn
- Learn more about the IEEE 1471 specification from the IEEE Web site.
- Read the white paper,
Modeling DoDAF Compliant Architectures, (PDF) by Cris Kobryn and Chris Sibbald (Telelogic, October 2004).
- Discover more about the Zachman Framework in
The Zachman Framework for Enterprise Architecture: An Overview, a white paper (PDF) by Thomas A. Hokel (Framework Software Incorporated).
- Rational Unified Process for Systems Engineering Part II: System architecture by Murray Cantor provides a review of the Systems Engineering extension to the IBM® Rational Unified Process® and describes aspects of system viewpoint-based modeling (The Rational Edge, September 2003).
- Learn more about the classic 4+1 views in
Architectural Blueprints -- The "4+1" View Model of Software Architecture by Philippe Kruchten (IEEE Software, November 1995).
- Read more about UML in Unified Modeling Language Version 2.0, by Bran Selic (developerWorks, November 2005).
-
Check out Kim Letkeman's six-part series, Comparing and merging UML models in IBM Rational Software Architect (developerWorks, July 2005).
-
In the Architecture area on developerWorks, get the resources you need to advance your skills in the architecture arena.
-
Browse the technology bookstore for books on these and other technical topics.
- Stay current with developerWorks technical events and webcasts.
Get products and technologies
Discuss
About the author | 
| | Benjamin A. Lieberman serves as the principal architect for BioLogic Software Consulting, a firm providing services on a wide variety of software development topics, including requirements analysis, software analysis and design, configuration management, and development process improvement. Dr. Lieberman is also an accomplished professional writer and author of The Art of Software Modeling and numerous software-related articles. Dr. Lieberman holds a doctorate degree in biophysics and genetics from the University of Colorado.
|
Rate this page
| |
