Role of UML and Visio in the Project

Chapter 6 - Documenting the Project
byAndrew Filevet al.?
Wrox Press ©2002

	Team FLY

So, having seen the common, major steps of a typical development project, let's start looking at each step in terms of how and where the UML and Visio play a role. Of course, not all Visio features revolve around UML, but in this chapter, we'll focus on UML produced by Visio.

UML as Documentation

Often, we see UML applied as a design tool, helping developers work out and express their ideas and designs in a consistent syntax that other developers will understand. One of the primary benefits of the UML is its ability to be read and understand by most developers, either because of their exposure to the UML directly or to similar notations, or just because the notation fundamentally makes sense even when read for the first time. Even in many trade journals and books, we see UML as a device that helps prepare for coding.

In other words, the UML is used to help craft designs and express ideas before code is written.

The impression is sometimes given, however subtly, that UML's benefit decreases once code is written and an application is deployed. That couldn't be further from the truth. Early stage application of the UML is certainly important, but it is also important to realize the long-term benefits of using UML as a device to capture the details of how and why a piece of software was built. The persistence of details about the design and implementation of a project is a concept we're going to explore in depth in this chapter. How will we use the UML to document our projects? That's a question we'll answer as the rest of this chapter unfolds.

What does the UML give us in terms of documentation capabilities? Many readers will be familiar with UML diagrams and understand how each of the common diagrams can add to the overall documentation of a project. For instance, a class diagram can describe classes, their attributes, and their relationships to other classes. That class diagram will most likely have been created during the design and construction phases of the project, but, it can serve several roles after code is written. First of all, the details in that class diagram should be made available to other developers within the organization in some kind of internal, technical documentation. The class diagram in some simplified form should also be available to support, implementation, and other groups who may need to understand, at least at a high level, how a particular application is constructed. Of course, the key is to ensure development team members take the time to keep documentation updated. Using a tool such as Visio certainly helps, but it is important to instill the expectation that documentation produced early in the project will most certainly be used in later stages.

So let's have a look at the application of UML throughout the software development lifecycle, stage by stage, and see how the concept of building UML diagrams with documentation in mind actually plays out. For our discussion let's create a simple application scenario: the development of an order entry application for our fictional client, the ACME company. Although we won't necessarily dig into the details of how this application works, it is useful to have a simulated project to refer to in the course of our discussion.

ACME has asked us to build an order entry application to help it take orders faster and with higher accuracy levels. It also expects some of the standard features of an order entry app to increase its levels of customer service - tracking inventory levels, estimating delivery time, reviewing order status online, etc. The basic features required in the application are the ability to create new orders, some kind of online order review mechanism for internal users, and an interface to ACME's manufacturing system. Of course, we have some schedule and budget constraints and we have a limited number of development and other technical staff - we do need to make this realistic.

Let's work our way through the major project steps starting with requirements development and review the following items at each stage:

• How can UML or other Visio produced documentation be used during the current stage?

• What types of users will consume this information?

• How can documentation produced at this stage benefit users and needs in subsequent stages?

• What changes can be made in our procedures and habits in early project stages to help support later project work?

Requirements Development Documentation

As we've already mentioned, the primary goal of requirements development is figuring out what the software product should do. How the goal of this stage is stated is rather simply, but the distinction between 'what' software should do and 'how' it actually does it is an important one. The 'how', the implementation, is saved for later stages - architecture and design. The larger or more complex an application is the more important it is to concentrate on requirements of the product instead of jumping into design and implementation details. It's a warning we hear all the time and it's a warning that most of ignore to some degree. The fun part of building software is actually designing and building, not sitting in long boring meetings discussing detailed aspects of software requirements.

Most project management and other software development lifecycle experts will tell you, however, that getting your project's requirements right from the beginning of the project is critical to ensuring success.

If requirements aren't done right your designs will suffer, your users could be left without key pieces of functionality, and you may have to answer some hard questions.

Have you ever seen or heard of an application that got into production but was never used because the users said that it didn't meet their needs? That was probably a project that didn't gather requirements properly.

Requirements development itself is more of an art than a scientific process. Moreover, gathering requirements for one application and group of users can be an entirely different experience when gather requirements for a different application with different users. Often times, finding and developing requirements is lengthy, tedious and, frankly, so much work with so little immediate, obvious benefit that it rarely gets done well, if at all. Hopefully, you'll see the benefits of doing requirements at all and, in the next few pages, how Visio and UML offer some tools to make requirements gathering easier.

The goal of developing requirements, the test to determine if we as designers and developers have captured what the application has to do, is a collection of necessary actions and behaviors of the application in the course of doing its work and a description of the interactions of various users and the application. A good requirements collection consists of at least two primary components - a requirements document and use cases. The requirements document is some kind of statement of various business, technical, and other requirements organized in a logical fashion around features of the product. Although there is no formal method for expressing requirements, it's common to find a requirements document full of direct statements about how the product should work or how results are generated in various situations. When written well, those statements are generally direct, unambiguous, and leave little room for interpretation by the reader. For instance, if our order entry application requires that web users have the ability to review their order history online we might see the requirement written as follows:

• The product will allow external users to access their order history via a web browser.

A more detailed requirement for our order entry application might relate to how we calculate shipping and tax expenses:

• The product will calculate shipping expenses using standard overnight carrier shipping expense tables.

• The product will calculate sales and/or value-added taxes by country or regional government regulations.

The best requirements tend to have some characteristics in common. First of all they are correct and succinctly stated. They also have to be verifiable. A good requirement is traceable. That means that we should be able to identify a requirement early in the project lifecycle and trace its inclusion and implementation throughout design and coding. Finally, a requirement has to be testable. Testing a requirement includes verifying that the final product has at least addressed the requirement and that it has implemented an appropriate solution. In other words, did the application deliver a feature or capability that meets the need, stated as a requirement, of some user of the application?

Clearly there are many methods of developing requirements and each has its own merits. Since most requirements come from application and business users, the best tend to focus on some method of capturing the information obtained from users and restating that information in some logical, consistent form. Once captured and restated, the information is conveyed back to the people from whom the information was gathered for review. The UML has a very useful tool for doing this called Use Cases.

Use Cases

Use Cases are the definition of a process. The process is generally a user or business process, but is always a series of logically grouped steps necessary to complete some task in a system. System in this case can be an application or manual process completed without the aid of software. Generally, use cases are written in either a text or graphical form. The text format is generally more narrative oriented, that is, more oriented toward telling a story about how a particular process is completed from beginning to end.

The Use Case Diagram is good at showing the major steps of a process and how those steps may be shared among other major processes.

At the requirements development stage of a project it is important to understand how a processes should work and what users are involved in that process. UML use cases are great at expressing that information. Let's start with the use case diagram then discuss the textual implementation of a use case.

As you have seen in other parts of this book and in other books and articles, business process and the users involved in these processes are represented in a use case by small ovals and little stick figures. An oval can represent a single discrete task or a more complicated but self-contained process consisting of many simple tasks. In fact, the oval shape in the diagram represents the use case itself. The scope of the use case itself generally determines how detailed the individual processes are. For example, a simple use case diagram representing the creation of a new order in our order entry application would contain this shape:

Obviously, creating an order consists of multiple steps, both by the user and by an application. The user would have to indicate that they want to create an order and give some details about products, quantities, etc. The application would also have to do some work that isn't immediately obvious in the single Create Order use case. If the detail of how an order is created is important to deciding what an application does, then you'll want to express the Create Order use case in more detail. Be careful, though, of falling into the trap of determining how an order should be created by the application during the requirements stage. At this point we are entirely interested in the business and user implications of creating an order and any requirements imposed on the application from their perspective.

If we wanted to illustrate the fact that internal and external users can use the Create Order use case, we'd add stick figures to the drawing to represent both user types. Although it's still a bit simplistic, here's what the drawing fragment would look like with an Internal Order Entry User and an External Customer role added to the Use Case.

As we know, the stick figures are called Actors in UML-speak. An actor can be a person or another application that executes the Use case. In this example we have to actors - Order Entry Clerk and External Customer who can execute the use case - create an order. Even if a diagram reader didn't know the details of creating an order, it is immediately obvious that there are at least two user groups.

The real benefit of the use case diagram is when you bring many uses cases together to illustrate an entire process. For instance, choosing a product from a catalog and buying it might constitute a common process that we'd like to document. A use case diagram representing that process and the actors involved might look like this:

These diagrams illustrates that our Order Entry Clerk and an external customer should have the ability to browse products, get pricing and inventory information, calculate shipping and taxes, and place an order. For the purpose of this use case, both an internal and an external user seem to need access to the same processes. In this example, that's entirely possible. In many cases though, we'd probably have one actor performing a set of use cases and another actor performing other uses cases within the same drawing. For instance, if our client's organization offered some kind of customer service or call center for customers to call to place orders, we might want those call center reps, still playing the role of an Order Entry Clerk, to have the ability to check customer credit. That's not something an external customer should be able to do. In the drawing, we'd express that as follows:

Notice the additional Check Customer Credit use case near the bottom of the drawing; only the Order Entry Clerk communicates with that use case in this process.

The other method for communicating use case information is in some textual format. Most requirements gathering processes rely on a textual format of some sort. Although the format and contents of use cases vary from organization to organization, the basic components of a written use case probably contain the following elements:

Use Case Element	Description
Number	A number or lettering scheme used to organize use cases and serve as an easy reference when use cases are included in other documents.
Title	A short description of the purpose of the use case. In our example above, we had "Check Inventory", "Create Order", etc.
Primary Actor	The main actor who executes the use case.
Secondary Actor	Any other user or application that can execute the use case.
Starting Point	A description of where the use case begins. This is typically a sentence or two describing the starting state of the use case, what the user is doing or sees, etc.
Ending Point	A description of where the use case ends. This is typically a short description of what the user sees or what state an application is in when the use case is completed.
Measurable Result	A description of what the use case accomplished. Sometimes the ending point and result described in this section are the same thing.
Flow of Events	A narrative of everything that occurs in the use case from Starting Point to Ending Point including a description of the Measurable Result. This element of the use case is the real content of the use case and should include as much information as possible about how the use case is executed.
Alternative Flow of Events	Anything that doesn't occur within the Flow of Events. This section generally includes exception and error handling and any other flow of events that isn't typical for this use case.

As an example, consider this use case for "Creating a New Order".

Using Use Cases for Documentation

As time-consuming as they may be to produce, use cases are one of the most powerful tools we have in software development to gather user requirements and capture them for future use. The first, immediate use of use cases is to capture requirements from users and use that information to help create some shared understanding of what exactly an application is being asked to do and what features and capabilities the application has to contain to make it useful to users.

Use cases also play an important role in helping project leaders develop initial scope and schedule estimates. After completing an initial round of use case development, developers and project managers should have a body of information to use as input for determining the complexity, and hence, cost in terms of budget and schedule for a development project. Of course use cases are not the sole input into the budgeting and scheduling process, but they offer the best source of "what do we need to do?" type information at this point in a development project.

Some of the overlooked value of use cases is their far-reaching implication for later-stage project tasks like testing, training, and post rollout support. Although testing shouldn't really have a defined start and a defined stop, it commonly occurs toward the end of a development cycle. Use cases can be tremendously useful for testing groups trying to write good test plans. Testing and Quality Assurance groups are charged with a double-edged task. First, they have to test the software as written. That includes installing the software and mimicking users in the field as we expect them to interact with the application. It also includes acting exceptionally - doing things a normal user really shouldn't do, but happen anyway. The second aspect to testing is determining if the software that gets delivered will actually meet the needs of users. If requirements are done well and use cases are written, the testing group can access that information and write accurate, real-world test scripts that help determine if our delivered software not only works as intended, but also meets the originally stated needs our of users. It's a common trap to test what the developers wrote and not what the users actually need.

Another use for the information contained in use cases is post rollout support. In most software development groups there's development done by a relatively small group of people. Then there are other, usually larger, groups of people responsible for rolling out the product and supporting customers when they have problems. Since the demands of time and other issues (like unsocial developers) often preclude a good flow of information about an application to customer-facing groups like support, use cases can be used to describe what an application should be able to do. The narrative portions of a use case give a lot of details in a, hopefully, easy-to-read format that support and other groups can use as a starting point in their understanding of the product.

Using Use Cases

Hopefully, I've made the point about trying to use use cases or a similar device in your requirements development. Whether you use them or not, the requirements development process is not something you can avoid. One way or the other you'll have to gather requirements if your applications are to succeed. Doing requirements deliberately, at the beginning of a project, is the best way to get a project started properly.

Just a few comments about building and using use cases before we move to architecture:

• When building use cases, focus on the user and other entities like external applications that interact with a process. That seems obvious, but the whole point of writing them is to capture a narrative description of what the user does, sees, etc. with an application or process. Many times developers write use cases themselves and it is very easy to change perspective from seeing the application as a user to looking out at the user from the application's perspective. If that happens you'll fall into the trap of building the application instead of figuring out what it should do first.

• Don't go overboard writing use cases. The phrase "analysis paralysis" applies here. Remember that we're paid to build software and not use cases. Pick the processes that are critical to the success of the application and write use cases for those processes. Another way to look at the issue of when to write use cases is by risk. Figure out what processes present the greatest risk and focus on writing use cases there first. Risk in this case could be the risk of a very complicated user process or even the risk of being able to pull off some process technically given stringent application integration requirements or something like that.

• Always review use cases with users. Always get them to buy in. For these statements about basing your understanding of an application's requirements on your use cases to have any merit, the data you collect in your use cases has to be absolutely correct. Test your use cases with users. Use cases are an effective technique for describing to your users what you understand of their processes.

	Team FLY