After the use cases have been identified, they must be described in detail. It must be stated what sequences of actions they represent, what external events will cause the various sequences to be performed, and so on. Without a more detailed description of the use cases, a use case will not be more than a named ellipse, which in most cases is not enough as a specification of the usage of the system. A Use-Case Description document should be prepared for each use case in the use-case model. How to describe the use-case model as a whole is discussed in the next chapter (Chapter 14, “Documenting a Use-Case Model”).
The use cases themselves can be documented in many different ways. The most common way to document a use case is using ordinary text describing the different sequences of actions (the basic flow and the different variants). There are two major reasons for this. One is that this form is the easiest way to present the behavior of a use case to other people, especially to nontechnical people. The other reason is that if a more formal technique is used for documenting the sequences of the use cases, the overall usage may be lost behind the technical details. Furthermore, it is usually more difficult and time-consuming to use such a formal technique. More detailed descriptions of the system are instead provided in the other kinds of models prepared for the system at hand.
Other kinds of description techniques that can be useful for describing a use case include state machines, activity diagrams, Petri net, operations, and sequence diagrams. Also other techniques may prove useful depending on the required level of formalism as well as any specific needs of the readers and other stakeholders. It is the intended use of the use-case descriptions that must guide which technique to use. If in doubt, we recommend describing the use cases with ordinary, structured text.
However, to produce a good description requires some proficiency in writing. Answering a few relevant questions is clearly a good strategy as a starting point for the use-case description. Some of the most important questions for the use-case description writer to bear in mind are as follows:
What is the purpose of the use case? The name of the use case is usually not enough to make people understand which flow is modeled by the use case. Even though most people will get a general idea of the use case by just reading the name, their interpretations might differ considerably. A short description (two to five sentences) will serve as an overview of the use case and help focus on what is important in the full description.
Which is the audience of the description? Depending on the background of the reader, different amounts of detail and explanation must be included in the description. An experienced user of a similar system will probably need less explanation than a newcomer. A developer will need more details than a user representative.
How many descriptions will there be of the use case? If only one description is to be produced, it must include all the information that anyone might be interested in. On the other hand, the description can be more focused on a subset of the stakeholders if multiple descriptions are to be used (see also Chapter 25, “Orthogonal Views”).
Which level of abstraction is to be chosen? It is quite possible to include all the minor details of the flows in the description, but who will be interested in them at this stage? In our experience, you should include only those details that the reader will need to grasp what the use case does. It is therefore important that you know whom you are addressing. Will the description be used when realizing the use case? If so, all the actions performed by the system must be included, such as business logic, error cases, and information handled in the use case. If the use case is to be mapped onto a collection of subsystems, the description can be given at rather a high level of abstraction because more detailed use cases will be identified and described within each subsystem (see also Chapter 18, “Component Hierarchy”). Is the description meant to be used only in discussions with management and users of the system? Then most details of what happens inside the system may be left out, and only details that can be perceived from the outside of the system should be described.
Is a black-box, gray-box, or a white-box description to be produced? This is similar to the preceding point. Should the description only describe the actions that can be perceived by the actors (black-box), should all actions except those having to do with the internal structure be captured (gray-box; the most common one), or should every action performed by the system be described (white-box)? For example, in the
Withdraw Moneyuse case in the ATM example, the user is aware of actions regarding validating the card and the PIN code, reducing the balance, and dispensing the money. However, the system will in fact also log every transaction, so that, in case something goes wrong, the bank will be able to track what happened, which may be of little or no interest to the user of the ATM when withdrawing money. At the most detailed level (white-box), the creation and deletion of instances inside the system as well as their interaction can also be captured. However, the white-box view is usually a description of the realization of the use case. Chapter 25 contains a more thorough discussion.How formal should the description be? Here the term formal is not used about a type of language. Instead, it refers to the manner in which the text is presented. In a small project where a one-time application is developed with project members who are familiar with each other, a more informal manner of style can be used. In large projects with distributed development and multiple iterations in which is developed a product that is to exist in many different versions, a much more formal style must be used, to make sure that all of its information is captured and available to all the team members. Another parameter is whether this is the first time the team is developing this kind of product (in which case, all the details must be captured) or if they have produced use-case models earlier (in which case, the descriptions can be made more abstract—but bear in mind that the next version of the product may be developed by another, less-experienced team).
After these questions have been answered and documented in a style guide, possibly accompanied by an example of a use-case description and a glossary, it is time to start writing. Unless the use case is very short and can be described right away, it is generally considered helpful to start by enumerating the major actions of the normal performance of the use case, beginning with what the actor does to start the use case. Next comes the system's response to that initiating stimulus, which is to be followed by the descriptions of the main actions and the communications from the system to the environment. All the details do not have to be included at this stage; the goal is an outline (see Figure 13.1).
In a ticketing system for airline tickets, a clerk can use the system to register information about customers, to find information about flights, and to register payment and issue tickets. One of the use cases is called
Order Ticket, which assists the clerk in registering the flights requested by a customer, assigning seats, and creating the corresponding ticket.
Figure 13.1. An example of the first draft of the description of the use case Order Ticket in an airline ticketing system.
After the first draft has been produced, it should be discussed with the different stakeholders to make sure they all agree on the purpose of the use case and the intended sequence of actions.
After this discussion, the description can be expanded with additional details. This also includes handling all the complementing alternatives to the choices made in the flow. If the basic flow includes what is to be done if a check evaluates to true, there must also be a description of what happens if the check evaluates to false. Unless the alternative flow is very short, it should be placed in a separate subsection.
Following is an example of a use-case description, including a summary of the use case in the Brief Description section, a Basic Flow description, and descriptions of Alternative Flows.
Note that the purpose of the use-case descriptions in this book is to provide an understanding of the use-case concept and how to describe use cases as well as an understanding of the different patterns and blueprints. These use-case descriptions are what we would expect to find in an industrial project, although they are somewhat simplified regarding details and functionality unnecessary for understanding the pattern or blueprint. In addition, the alternative flows are often fewer and shorter than normal because we do not want the examples to diverge because of exceptions and error handling.
It is important to remember to include exceptional cases, for example, if no communication connection can be established with an actor, perhaps because the network suddenly breaks down, or if part of the information could not be stored in the system, perhaps because the database management system times out, and so on. Situations of this type are often forgotten in the description of the use cases. Obviously, it will cause the implementer a great deal of trouble to decide how to solve them. Even worse, they could even cause the system to break down because no solutions have been implemented. A typical example of such an exceptional case is the flow No Connection with Airline in the preceding description.
What most people experience when they start describing their use cases is that the work often comes to a halt. They do not know what to write! This has nothing to do with being uncomfortable writing descriptions (although that might be a problem as well). Instead, they are—far too often—not clear about what the system should actually do. The paramount need of having access to people with the right business expertise and the authority to make decisions cannot be stressed enough!
When producing the first draft, the main focus should be on describing the flow of the use case and possibly identifying any questions, not to answer them. Experts on the business and its usage of the system as well as experts on technology should also be brought into the project at this stage to answer questions that arise. It is much easier to schedule meetings with these persons at this stage instead of trying to find them and have them answer single questions on a number of occasions during the project. If proper use-case descriptions are not produced, most problems will not pop up until at a late stage in the project. Then, usually an implementer writing the code must solve the problem, while the deadline is approaching quickly.
After description of the use case has been produced, it must be reviewed to make sure it captures the correct flow. Obvious reviewers are the end users and the customer (or the product owner, if the system is developed by the same organization that will use it). Other reviewers who are relevant in the review process include developers and testers to make sure the description includes enough details, architects to make sure the use case utilizes the different parts of the system in a correct way, and usability experts to ensure that the interaction between the actors and the use case is suitable and satisfactory.
This section provides some guidelines to be used when writing a use-case description. You can use them as a starting point for a project style guide.
Use a consistent style—. Use common words and phrases in short sentences when describing the flow. The text will be easier to read and understand.
Prepare a template and an example—. It will be easier to produce uniform descriptions.
Use subsections—. When organizing the text, use subsections in the same way as you do when writing other text. The text will be much easier to read.
Describe the flow as something that actually happens—. Even if the system has not been built yet, describe the flow as something that actually happens to make it easier for the reader to get an idea of the system.
Use the active voice—. To make it clear who initiates the interaction, the system or an actor, use an active voice writing style.
Always use the name of the actor in the interaction—. Do not just write “the actor.” This makes it clear which actor is involved.
Capitalize the names of the actors—. This will make it clear that you are referring to an actor and not to some information about the actor inside the system.
Use short paragraphs with one input—. A paragraph should contain no more than one actor input, which should be given as the first sentence. This makes the text more structured and readable.
Be explicit about what information is sent, received, stored, and so on—. Never use phrases such as store the information about X unless you are referring to information explicitly stated one or two sentences back. Otherwise, the reader will have no clue what information you are referring to.
State business rules explicitly—. In a separate section in the use-case description or in a separate document to be used in all use-case descriptions, state business rules explicitly. Reference these business rules in the description of the flow. This will make the text much easier to read, and the business rules can be maintained and enhanced separately.
Create separate sections for details—. If there are many information attributes, list all the details in a separate section of the use-case description that can be referenced from the description of the flow. In this way, the description of the flow will not be cluttered with a lot of details that disturb the understanding of the flow. If the same information attributes are used in several use cases, put them in a separate document and treat them in the same way as business rules.
Identify nonfunctional requirements—. State nonfunctional requirements explicitly in a separate section of the use-case description or in a separate document to be used in all use-case descriptions.
Do not mention GUI design details in the flow—. For example, do not identify characteristics of the GUI such as drop-down lists, lists of radio buttons or check buttons, or text fields. The GUI design will most likely be changed in a later version of the system, and if no mention is made, the use-case descriptions need not be modified.
Do not mention design or implementation details in the flow—. Avoid using terms such as applet, database, and process. This would restrain the designers using the use-case model as input to making design decisions. Changing the implementation technology should not imply changes in the descriptions of the use cases. Furthermore, the use-case model will become more general this way. For example, the same use case can be used for presenting information on a web page as well as on a mobile phone screen.
Specify information retrieval and calculation means—. Be explicit about how information handled in the use case is retrieved or calculated.
Confirm enough details are included—. Make sure the description contains enough details so it is possible to produce a use-case realization based on it, to estimate time and resources, and to identify all major architecture components.
Describe long loops separately—. Describe the body of a loop directly in the flow only if it is short (less than half a page). Otherwise, put it in a separate subsection. If not, the overview of the flow will be lost.
Define long alternatives separately—. Describe the alternatives in a condition in the flow only if they are short (less than a third of a page). Otherwise, put them in separate subsections.
Specify where use case ends—. Explicitly state that the use case ends at the appropriate place(s) in the flow description.
Avoid cross-references—. Never reference (sub-) sections in other use-case descriptions. These may be modified later, which will make references outdated.
Reference extension points of other use cases—. When defining an extend relationship to another use case, only reference extension points of that use case. The flow or the description of the flow of that use case might be reorganized later, which will make other references obsolete.
Reference logical locations within a use case—. Never reference paragraph numbers or line numbers. These will be modified. Reference locations defined by the state of the use case or (sub-) sections within the use-case description instead; these are more stable.
Do not use explicitly tagged keywords—. The text will be harder to maintain, and the reader is most likely not a programmer and therefore not used to the notion of keywords.
Prepare a glossary of words and terms—. This glossary is to be used by persons producing use-case descriptions, which means that the same terminology will be used in all the descriptions. Furthermore, the reader can look up the precise meaning of a word in this particular model and project.
Diagram complex flows—. If the flow is complicated, prepare a state diagram or activity diagram to make it easier to follow the text.
Diagram nontrivial cases—. In nontrivial cases, prepare one diagram for each use case, showing the use case in the middle of the diagram and all the elements it has relationships with in a circle around it together with the relationships. Put the actor initiating the use case on the same side of the use case from which you start to read. Included and parent use cases are normally put at the top of the circle.
How include, extend, and generalization relationships to other use cases affect the description of the flow is described in the Documentation of . . . sections of the chapters presenting these relationships.
The core of a use-case description is, of course, the description of the sequences of actions. What else is to be included in the document depends largely on the needs of the project, the documentation standard of the organization, and so forth. Therefore, it is difficult to present a universal template for this kind of document. However, some sections tend to occur in most use-case descriptions, as shown in Figure 13.3.
The Brief Description consists of two to three sentences that summarize the usage modeled by the use case. Apart from the flow description itself, this is the most important section of the document, and must not be excluded. Mention at least the initiating actor so that the reader understands the context of the use case. If the use case is abstract, this should be stated here.
The next section, Relationships, presents the context of the use case in the use-case model—that is, what relationships the use case has to other use cases and to actors. Often this is done by including a diagram showing the use case surrounded by all use cases and actors it has relationships with.
This kind of diagram, showing the use-case model as seen from the viewpoint of one of its elements (in this case, a use case) is sometimes called a local diagram of the model.
The diagram may be replaced by a textual description, in which case this section usually has subsections for the different kinds of relationships the use case has with other elements.
For extend relationships, not only the use case at the other end of the relationship should be stated here but also the condition and the extension point of the base use case. Note that an extend relationship is documented only in the description of the extension use case—that is, not in the base use case because this is to be independent of the extension!
Of course, the opposite goes for include relationships, which are documented only in the base use case, not in the inclusion use case. An include relationship is fully described here by just stating which use case is included.
The description of associations with actors should include multiplicities, if such are to be used in the project (see the section Interaction Between Use Cases and Actors in Chapter 5, “Modeling the System Environment”).
Different conventions for the Relationships section can be applied, such as not including the section at all for use cases with a very simple context (for example, consisting of only one association to an initiating actor). On the other end of the scale, for use cases with extremely complex surroundings, it might be convenient to include both a diagram and a textual list of the relationships with their characteristics. The drawback is that there will be more documentation to maintain and keep in sync. Another option is to skip the Relationships section and instead include a diagram as an appendix of the use-case description.
The Extension Points section is used when relevant, defining all extension points in terms of name and location in the flow. Remember to keep the extension point locally defined; that is, the name must not indicate what is expected to be added at the extension point. Also avoid referring to labels such as numbered sections in the flow description.
There may be multiple flows in the Basic Flow section of a use-case description. These flows are of the same significance, which will make it impossible or inappropriate to refer to one of them as basic and to the others as alternative. Instead, you can number them Basic Flow 1, Basic Flow 2, and so on. Even better would be to name the different flows in a descriptive manner (for example, Update Order and Delete Order). It is also wise to enumerate all those flows at the top of the Basic Flow section so that it becomes clear to the reader from the start that there are multiple basic flows.
Depending on the characteristics of the different flows of a use case, you can use different headings in the subsequent sections, such as Alternative Flows, Exceptional Flows, and so forth. Use only necessary headings and exclude the rest!
Use-case descriptions often include a final section called Special Requirements. Any requirements regarding this use case that are not naturally included in the flow descriptions can be listed here. In particular, this includes nonfunctional requirements, such as requirements on response time, time out, number of concurrent users, and so on. Many projects prefer to collect all such requirements in a separate document; if so, this section is excluded.
Apart from the sections listed here, which are used in most use-case descriptions, you can add others when needed. One example is to include sections for pre- and postconditions. A precondition describes in which state the system is when the use case is to be initiated. Its purpose is to set the context for a reader of a use-case description. Note that it does not state a condition that the system will check before enabling the use case. All actions to be performed by the system, including checks whether a condition is fulfilled or not, must be included in the flows of the use case. A postcondition is similar to a precondition, but it tells the reader the state in which the system is after the use case ends.
Note that the postcondition describes all possible end states of the use case, including the error states, and not only the state reached when ending successfully; whereas the precondition describes the state in which all possible flows of the use cases can be initiated. Obviously, you can use pre- and postconditions when describing single sequences within a use case.
Another example is a section enumerating all outstanding issues that are to be resolved. With this section, you can keep all questions together with the description without cluttering up the description of the flow. At the end of the project, the section is (hopefully) empty, and you can remove it when finalizing the documentation.
In general, additional techniques like using paragraph numbers in the description of the flow can be used during the development of a use-case description.