Because the behavior captured by a use-case model is made up of its contained use cases, it will be fully documented by the descriptions of these use cases (see Chapter 13, “Describing Use Cases”). However, mainly for practical reasons, the documentation of a use-case model as a whole is usually complemented by a few more documents.
In general, the purpose of these documents is to give an overview of the model, both its structural and behavioral contents. It is therefore customary to produce a Use-Case Model Survey document as well as a set of Use-Case Diagrams.
A Use-Case Model Survey is a text document whose main part consists of brief descriptions of each use case contained in the model, as well as of all its actors. The Use-Case Model Survey should also contain a concise Introduction to the model as a whole, describing the purpose of the system and pointing out the core use cases matching the main purpose of the system being modeled (see Figure 14.1). This is normally given in terms of half to one page of text in a separate section at the beginning of the document. Therefore, when approaching a system modeled with use cases, this is the first document to read; it gives a brief introduction to the system and to its use cases.
Actors, the next section of the document, includes brief descriptions of all the actors in the model. Because actors represent entities outside the system in focus, in other words by definition outside our control, there is not much that can be said about them. However, it is very important to capture for each of them precisely what their role is toward the system, so that there is no risk of ambiguity. Therefore, we should provide a paragraph consisting of one to three sentences for each actor, always remembering to focus on its role toward the system. This is not as easy as one might think. Often these short descriptions tend to describe the role in the organization as a whole represented by the actor, which is in fact more or less irrelevant in our case because we should focus on the system. It is possible to avoid this error by writing two paragraphs for each actor, one focusing on the role in the organization and one on the role we are actually interested in. Normally, the former can be omitted in the final document, but in some cases it provides information to the readers of the document that will make the model easier to understand. It is important, however, to make sure that the difference between the two roles is made clear.
The last section, Use Cases, which makes up the bulk of the Use-Case Model Survey, contains brief introductory descriptions of each use case in the model. This is also where we describe the pattern and blueprint usage in the model. As an introduction to this section, we list the use-case patterns and blueprints that have been applied, together with explanations when appropriate. This will give the reader a better understanding of the rationale behind the structuring and descriptions of the model.
The description of a use case in the Use-Case Model Survey document and the brief description in the Use-Case Description document of that use case should be identical. This section of the Survey will therefore, in essence, be a compilation of all the brief descriptions of all the included use cases. It therefore functions as a convenient introduction and overview of the model. Obviously, it is very helpful if a tool can assist in keeping these texts identical, for it is a well-known fact that it is cumbersome to maintain two different descriptions of one and the same thing, especially if their purposes coincide. Note, however, the point here is not that the two texts are identical, but that they express the same information.
The use cases in this section may be organized in groups according to different criteria, for example, in service areas and/or in alphabetic order. The latter may be convenient for small systems with no particular logical order between the different use cases. However, for medium-sized models, just ordering the use cases alphabetically usually makes it hard for readers to get a clear overview of the system behavior. It is then better to identify various service areas, grouping use cases together, and presenting them in separate subsections. If the use cases are presented in subsections, you may consider listing the used patterns and blueprints in the subsections rather than in the introduction to the use-case section as a whole. With the intended readers in mind, choose what would seem to be the more suitable alternative.
In rare situations, where the use-case model consists of a very small set of use cases, the use-case descriptions may be included in the Use-Case Model Survey directly, making this the only text document describing the model. This has one obvious advantage—there will be only one document to read and maintain—as well as a number of obvious drawbacks—the Use-Case Model Survey will have to be revised, reviewed, and approved whenever there is a change in one of the use cases.
One of the first things a reader will look for to get an overall picture of a use-case model is the use-case diagrams depicting the model. These may be presented in the existing sections or in a separate section of the Use-Case Model Survey, as appendices of the Use-Case Model Survey, or handled separately.
However, it is practically impossible to create a single diagram showing all the use cases of a model. Instead, the model will be graphically documented in a set of diagrams, each of them showing a subset of all the actors and use cases in the model, selected according to some given criterion (see Figure 14.1). These criteria should be given by the different kinds of designated readers of the model.
Figure 14.2. The elements in a use-case model are usually presented in a collection of diagrams. Some elements, such as the use case Retrieve Customer Information, participate in several diagrams, whereas others, such as the use case Register Ticket, appear in only one diagram.
There are mainly three different kinds of readers of the Use-Case Model Survey: those interested in a particular part of the system, those representing the users of the system, and those interested in a particular use case. It is therefore a good policy to prepare three different kinds of diagrams. Obviously, the diagrams will vary considerably depending on the size and complexity of the system and who the target readers are and so forth. The different kinds of diagrams are as follows:
Overview, or global, diagrams—. An overview or global diagram presents the use cases and the actors of one of the (functional) areas of the system. If the diagram becomes too crowded, it should be split up into multiple diagrams. All these global diagrams together show all the actors and use cases of the model, including all their relationships. Some of the elements may be presented in multiple diagrams to make them easier to understand.
Actor, or local, diagrams—. A local actor diagram presents one actor and all the use cases the actor is associated with, all the parent actors of the actor, as well as the generalizations between them.
Use case, or local, diagrams—. A local use-case diagram presents one use case and all the actors the use case is associated with as well as all the use cases to which it has generalizations, include, and extend relationships.
The use-case diagrams may well overlap; that is, a use case (or an actor) may be shown in several diagrams. Sometimes some relationships involving a certain use case are not relevant in the context depicted in a certain diagram, but are better shown in another diagram where this use case also appears. Therefore, just because a use case is present in a diagram, the whole truth about that use case is not necessarily shown there! It is important to make sure the diagrams together show every use case, every actor, and every relationship to be found in the model.
Apart from the core use-case model documents, which consist of a Use-Case Model Survey, Use-Case Descriptions, and Use-Case Diagrams, other documents may be prepared. Which of them will be needed depends on the type of project and the kind of system to be developed.
Often it is necessary to compile a Glossary to make sure that the terminology used in the use-case descriptions is consistent. In some cases, it is even appropriate to complement the Glossary, or even replace it, with a Domain Model. This is a model of the concepts used in the business domain of the system, including relationships relevant within the project.
Another document usually produced when a use-case model is being developed is a document where all the nonfunctional requirements are captured. These are requirements that are not easily expressed as use cases, such as response times, volumes to handle, regulations to adhere to, security requirements, architectural requirements, and standards to use.
Some systems are highly dependent on a set of business rules, guiding the procedures of the system. These may of course be included in the affected use cases, either directly in their flow descriptions or in a separate section of the description document, but it is often more convenient to keep them in a separate Business Rules document. See Chapter 16, “Business Rules.”
Other kinds of rules affecting the performance of the use cases in the models, such as algorithms, printout templates, and so forth, may be treated in the same way as business rules, which means that they may be documented in the same document as the business rules, under separate subsections, or in separate documents, whichever is more convenient.