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.

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).

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.

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.

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 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).

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.

Back to top

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).

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.

Back to top

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).
  
  
• Browse the technology bookstore for books on these and other technical topics.
  
  
• Stay current with developerWorks technical events and webcasts.
  
  

Get products and technologies

• Download a trial version of Rational Software Modeler.
  
  

Discuss

• Participate in the discussion forum.
  
  
• Check out developerWorks blogs and get involved in the developerWorks community.
  
  

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 article

Comments

Back to top

Table of contents

• Introduction
• Model forms
• Model themes
• Diagram pivots
• Summary
• Resources
• About the author
• Comments

Next steps from IBM

Rational Modeler is a free, UML 2.1 based environment that helps users to improve communication by specifying, visualizing and documenting their system, architecture and software designs using a standard graphical language.

---

• Try: Download a Rational Modeler, a free, UML 2.1 based environment for specifying systems, software, and architecture.
• Buy: Rational Modeler Rhapsody Corporate Edition

Dig deeper into Rational on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers