CHAPTER 8

AUTHORING USE CASES

Camille Salinesi

Université Paris 1 Panthéon, Sorbonne, France

APPLICABILITY

The proposed guidelines were developed in a tool named L'Ecritoire, which was implemented during the European-funded CREWS project on Co-operative Requirements Engineering With Scenarios. Theoretically grounded on a Fillmorian approach of natural language, they were empirically validated through a number of scientific experiments, and were used to good effect in projects with Europe-wide companies such as Alcatel, Eurocontrol, and Renault.

Experience shows that their main flaw is that they can hinder creativity when beginners try to apply them. However, once acquired by the authors, it is most often found that these guidelines may become extremely efficient. In particular, they reveal the importance of having an explicit view of the UC meta-model even when writing in natural language. Besides, they can easily be adapted, for instance to different languages, corporate or project policies, methodological and project constraints, and so on.

POSITION IN THE LIFE CYCLE

Let us take the example of a financial company that has decided to replace its old credit management system. A number of stakeholders are immediately involved in the project. As usual, they not only have different backgrounds, skills, culture, and so on, but also different expectations from each other.

• Salesmen want to sell the products they create without being restricted by other users or by the system itself.
• Risk managers want to reduce the risk presented by the contracts made by the salesmen with customers.
• Customers want to get credits that match their financial situation and their expectations.
• Developers need good requirements specifications, system analysts expect that a good system is produced, and so on.

If Use Cases are used as a common language between all these stakeholders, then it is crucial that they meet all these expectations at the same time. With respect to the form, this means that Use Cases can be as different as completely unstructured rich stories about the system usage, or fully structured texts supported with diagrams and statements in a specification language.

This is the same phenomenon from the project life-cycle point of view: different kinds of Use Cases can be authored and used throughout the life cycle. Indeed, once a Use Case is identified, its scenarios written, completed, corrected, discussed, and revised, and if necessary split into or merged from other Use Cases, they can still be formalized, transformed, transmitted to other stakeholders, matched with other kinds of models, analyzed to elicit new requirements, to produce specifications, to inform system design coding and testing, and more generally to support any other purpose in each activity of the life cycle.

Given this diversity, answering the question how to author a good Use Case is a difficult one, if a specific context has not been chosen. Rather than trying to deal with all possible contexts in which Use Cases might be authored, we have tried in the remainder of this chapter to focus on the authoring of Use Cases in the context of initial requirements discovery. We hope that this chapter answers most of the questions you may have, and that the techniques proposed can easily be applied to your own project situation.

KEY FEATURES

• Any Use Case should be written with a goal in mind.
• A Use Case is always composed of several scenarios that describe alternative ways to try and achieve the goal.
• All scenarios of a Use Case should be written in a consistent manner; this holds good not only for the style used in the scenarios but also for the scenario content.
• Style guidelines and content guidelines can be used as a rule to guide scenario writing as well as to check their validity.
• Once validated, scenarios can be analyzed to look for other Use Cases and scenarios.

STRENGTHS

It is easy to take a sheet of paper and draw a Use Case model, and then write a story for each bubble in the model. It is also easy to ask stakeholders to fill in a scenario form, such as the ones you will find all over the web. But, it is less easy to author Use Cases and write scenarios that are useful for dialogue with other stakeholders, or that match their goals. It is even less easy to foresee what you will get when you ask a stakeholder to author a Use Case. We believe the best way to author Use Cases is to decide first exactly what a Use Cases should look like, and then to create them by applying guidelines that apply the chosen definition, and that are well-understood and accepted by all.

The main strength of such an approach is of course that it is systematic. Besides, once defined and agreed, guidelines can also easily be understood and adopted by newcomers. It is a set of easy-to-use guidelines (as long as they are understood), as it does not require any complex or costly tool, and is nonintrusive as—apart from initially getting familiar with them—it does not require any supplementary activity. Lastly, Use Case authoring guidelines can be used to document the project, and can be adapted and reused from one project to another.

WEAKNESSES

The main weakness of the guidelines approach is that there are few automated facilities available on the market to systematize their application. As a result, it is hard to ensure that Use Cases are actually authored productively. Therefore, Use Case quality is a function of people's ability to apply the guidelines. This ability depends on the Use Case author's understanding the guidelines, and on the guidelines' correctness, clarity and ease of use. Tools (such as Scenario Plus 2003) can be used to retrospectively check that a number of Use Case features are correctly implemented. However, the facilities provided by scenario authoring tools are still relatively limited.

Another important weakness of guidelines is that people have to learn them before becoming fully productive with them. Of course, this learning phase is not instantaneous. As long as authors are not fully familiar with the guidelines, the general quality of Use Cases will remain low (in particular on the creative aspect). This weakness can be dealt with in three different ways,

• By training Use Case authors and testing their authoring skills;
• By introducing Use Case authoring guidelines in stages; and
• By complementing the guidelines with other techniques, for example verification tools to check correctness, or workshops to enhance creativity.

TECHNIQUE

Why Do We Need Guidance on Authoring Use Cases?

Authoring a Use Case is not just a matter of writing its main scenario. The authoring activity also covers the identification of the Use Case, its completion, verification, correction, and sometimes transformation from one notation to another (generally more formal) notation. So, authoring a Use Case is not a task as simple and easy as it might look at a first glance.

There are several questions that authors should attend to. For instance,

• What is the Use Case boundary?
• Is there a better name for this Use Case?
• How many scenarios should we have per Use Case?
• Which scenario should we start with?
• How detailed should the description be?
• Is this a whole Use Case or just a scenario?
• Is it normal that this scenario excerpt appears in several Use Cases?
• Is it OK to put the alternative here?
• How do I deal with events that can occur anytime?
• Is this Use Case sufficiently clear, complete, well structured, and well presented?
• What misinterpretations could there be?, and so on.

If you are able to handle these questions, your approach to Use Case authoring is probably mature. But what about the other stakeholders? Can they provide the same answer as yours? Can they even answer these questions? The purpose of these guidelines is to help people learn what good Use Cases are like, by indicating how they should be authored. Authoring guidelines, in other words, also help people learn what Use Cases are. The better stakeholders know the guidelines, the better they are at analyzing them, transforming them for different purposes, and communicating them to other stakeholders.

In contrast, if stakeholders have no idea how to avoid ambiguous Use Case names, poor style in scenario descriptions, inconsistent use of terminology, inadequate structuring, or mix up levels of details, it is very likely that their Use Cases will lead to poor communication, confusions, misinterpretation, inconsistencies, inappropriate design decisions, more time spent in revising models, incomplete system validation, late correction of scenarios and costly backtracking on design decisions, and so on.

Therefore, the most important prerequisite when authoring Use Cases is certainly to be aware of Use Case style and contents. This chapter shows how to make explicit the style and the content expected in a Use Case, and indicates some of the most typical errors of Use Case authoring. The reader is free to select, transform, complete, re-present, and restructure these guidelines according to the particular needs of projects. Figure 8.1 summarizes the most commonly used contents of Use Cases.

Use Case Attributes

The main attribute of a Use Case is its name

Use Cases and scenarios are generally at user-system interaction level, that is, they describe how a user interacts with the system to get something done. At this level, Use Cases and scenarios emerge by focusing on the services provided by the system. From the system point of view, such Use Cases are described by the actions needed to provide services to the user. Conversely, from the user point of view, Use Cases describe how system services can be used to achieve a goal (Rolland et al 1998). All in all, a Use Case is thus a goal that the user shares with the system. The most appropriate name for a Use Case is thus the goal that the system and its user share. Business analysts also employ Use Cases to define business processes, in which case the ‘system’ is generally socio-technical and may not involve any particular product or equipment (such as computers and software).

FIGURE 8.1 Structure of a use case
Many variations on this theme exist. Note that the only items normally shown on a Use Case diagram are Actors (named icons) and Use Case Names (in bubbles). All the remaining structures are documented in text (or database fields of various types). © Ian Alexander/JBA Ltd 2003.

Goals are the most important attribute associated with Use Cases and scenarios, as they identify their content, delineate their scope, and identify in a simple way what the system should do. Any goal identifies some objective. Such objectives can be at the service level, but can also be at the business level, or more specifically at system function level. Besides, a goal statement can express the objectives that the system's user has in mind, but it can also identify the objective of a company and therefore identify the working context of the system, or more specifically identify things that a component of the system should do. There are therefore, at least three levels at which goals can be stated: the context level, the service level, and the physical level. At the context level, business goals define what an organization wants to achieve with the system, at the service level every goal identifies a service that can be obtained from the system by interacting with it, and at the system level system functions are operationalized and affected to system components.

In order to better understand the scope of a given scenario or Use Case, one must first ask the question: ‘what is the goal which is illustrated?’ Identifying whether we are dealing with a scenario, with a Use Case, or whether several scenarios and Use Cases have been mixed up is then a straightforward process, which immediately results from the following definitions:

In order to define the scope of a scenario or a Use Case, it is thus necessary to

• Delineate the main goal that the scenario or Use Case should describe;
• Identify the different ways to achieve this goal (normal ways, unwanted endings, as well as those taking place when exceptions occur); and
• Associate a scenario with each way to achieve the Use Case goal.

Other Attributes

It is clear that Use Cases are more than just a collection of scenarios describing normal and exceptional interactions between a system and its users: Use Cases have numerous Attributes (GG2). For example, a Use Case can also carry information about:

• The scope, the level of abstraction/detail at which the Use Case is described;
• A list of terms (e.g. agents or objects), links to a project glossary and some of their properties;
• Preconditions, triggering event, frequency, initial situation, invariant properties;
• Success conditions, possible events, repetitions, concurrency, failure conditions, final situation;
• A description of the primary and secondary actors, of the objects involved in the Use Case;
• Dependency links, extensions and relationships to other Use Cases, scenarios or actions;
• An activity diagram for each actor;
• A sequence diagram that formalizes the message passing between the Use Case actors;
• System requirements attached to the Use Case;
• Priority, change history, decision rationales, open issues, etc.

The Use Case templates available on the web show that the list of attributes varies from one project to another. It is easy to develop your own template as a model file using any word processor. Default templates are also made available by Alistair Cockburn at URL http://members.aol.com/acockburn/papers/usecase.htm. The information developed using such a template can be managed manually, or using tools such as the Select Enterprise Case tool or Rationale's Requisite Pro.

Guidelines for Authoring Use Cases

There are different ways to provide guidance on a given activity. This goes from enforcing the achievement of a predefined sequence of actions with tools (as in wizards) up to adaptive situational advisors that suggest undertaking different kinds of actions in different contexts (as in assistants). The guideline approach is in-between as (i) it does not enforce a way of working, (ii) the way of working proposed in the guidelines can be adapted in advance as well as on the fly (e.g. the most adequate guidelines can simply be selected depending on the context), and (iii) it is a nonintrusive approach as long as the guidelines user is able to learn the guidelines rather than go forth and back between the guidelines and the Use Case authoring tools.

There are three important aspects in Use Cases: their general structure, their contents, and the style that can be used to present them. Therefore, we propose to assist Use Case authors with three series of guidelines,

• general Use Case guidelines,
• scenario contents guidelines, and
• scenario style guidelines.

Each series of guidelines is presented under the form of a list of suggestions that indicates what to put in a Use Case, what to write in scenarios, and which style to adopt while writing them.

Scenario content guidelines advise the author on the expected content of his/her text. Informally speaking, they indicate the ‘what’ of the scenarios in Use Cases.

Scenario style guidelines provide recommendations on the style of the expected prose. They address the ‘how’ of the scenarios. Scenario style guidelines aim to help scenario authors to adopt a good style, in conformity with the expected textual structure of scenarios.

Linguistic theories suggest a dependency between the two kinds of guidelines. This implies that style guidelines should not be applied without taking care about content as well. Conversely, content guidelines cannot improve scenarios without appropriate style. Therefore, the scenario style and content guidelines are complementary; they were developed to tackle both the surface and the deep aspects of the scenario language (i.e. the language used in textual scenario descriptions), as the linguistic theories suggest. A scenario can be written in a correct style but have the wrong content. For example, it could be out of the frame of the problem domain. Conversely, a scenario with valid content can be written in a bad style, and for example lead to an erroneous interpretation.

The guidelines proposed here were defined to help authoring Use Cases as defined in the CREWS-L'Ecritoire approach, but they can easily be adapted for other purposes, your own definition of Use Cases, the level of formality and structure you aim at, and so on.

For example, other guidelines exist on structuring Use Cases and scenarios, making them more complete, precise, and consistent in terminological use (see e.g. the Rational Unified Process, or Cockburn's Writing Effective Use Cases). Integrating these guidelines in your methodological environment is then a matter of defining the specific details of your Use Cases and scenarios, identifying the contexts in which the Use Cases will be authored, adapting the guidelines to these contexts of use, and training the Use Case authors to read, learn, and apply the guidelines.

It is crucial that authors see application of the guidelines as mandatory. The purpose of Use Case authoring guidelines is to avoid requirements issues caused by poor Use Case descriptions. It is now well documented that too often, such issues lead projects to overrun their schedules and budgets.

The reason for having informal guidelines lies in the human-centered nature of scenario writing and Use Case authoring activities. It is not possible, or even desirable, to control such activity completely. In fact, experiments have shown that applying more control makes Use Cases less creative and less complete. It is thus the responsibility of Use Case authors to apply the guidelines. If necessary, authors can use the guidelines as a checklist to verify the quality of their Use Cases (GG5).

General Use Case Guidelines

Authors should first make sure that the system goal that is going to be illustrated is clear. The initial goal will not only identify the individual Use Case for the rest of its lifespan, but it also provides the first input for describing its content. Our approach to state goals (and hence to name Use Cases) is to write a predicate composed of a verb and several complements. A quick look at the other chapters in this book (e.g. Chapters 12 and 17) will show you that this approach is the most widely used. Other Use Case attributes can also be used for a more accurate identification. For instance, the RUP recommends identifying the actors involved in the Use Case before entering into the detailed description of each scenario in the Use Case.

A very common approach to Use Case authoring is to describe each Use Case scenario by scenario (GG3). Most often, authors start by thinking of the most probable or common sense Use Case output. This is documented as a normal scenario, that is, a scenario that results in reaching the Use Case goal (so in this approach there can be several normal scenarios in a Use Case).

Other scenarios, such as alternative scenarios, scenarios describing exception handling, or less frequent scenarios are usually identified from the first one, then authored in turn to complete the Use Case description. This way of working has the advantage of being stepwise: the Use Case description does not have to be complete to provide a good idea of its content. Besides, elements of the initial scenario can be reused in alternative ones, which tends to increase consistency of the descriptions (GG4). However, a systematic application of this way of working requires authors to be aware that one scenario describes one path through the different possibilities, and that all the alternative scenarios should be described separately to preserve consistency.

Scenario/Use Case Style Guidelines

The different style guidelines proposed below deal respectively with: (i) the style to be used to describe scenario interactions, (ii) the style to be used to express flows of actions, (iii) the style of initial states and of final states, and (iv) the terminology to be used in scenarios.

Style of scenario interactions

The style guidelines SG₁, SG₂, and SG₃ deal with the style to be used for describing correct interactions.

SG₁ aims at helping the scenario author in writing complete interactions. On the other hand, SG₂ and SG₃ deal respectively with the relevance of the elements described in interactions and with the adequacy of the interactions described.

Style of scenario flows of actions

The content guidelines CG₃, CG₄, CG₅, and CG₆ define the content of the scenario flows of actions. The style guidelines SG₄, SG₅ and SG₆ complement them by advising on the difficulties and errors due to inappropriate style in the description of sequences, repetitions, concurrency, and constraints in the flow of actions of scenarios.

Style of scenario initial states and final states

Each scenario begins with an initial situation, and terminates with a characteristic final situation. The purpose of the style guideline SG₇ is to advise the scenario author on how to describe the initial and final states of scenarios.

Describing states within the scenario flow of actions presents several difficulties: it makes implicit the role of the states with respect to the scenario, and it hinders the correct differentiation between states and flow conditions. The description of the various situations met during scenarios, and in particular of the initial situation and of the final one, should be put outside the description of the scenario flow of actions.

Style of scenario terminology

The terminology is as important in scenarios as in other kinds of requirements-engineering model. The style guidelines SG₈, SG₉, and SG₁₀ advise scenario authors to use terminology that is consistent, and non-ambiguous. They also explain that the terms used to define Use Cases and scenarios (including the terms ‘Use Case’ and ‘scenario’ themselves) should not be used in scenarios.

Scenarios/Use Case Content Guidelines

The purpose of the content guidelines is to point out to scenario authors the different information elements provided by these scenario definitions. Each guideline tells the scenario author something about the required content of his/her scenario. The content guidelines deal respectively with

• The general definition of scenarios as ‘description of a single flow of interactions’;
• The content of the different kinds of interactions that can be described in scenarios;
• The different kinds of flows of actions used to express the organization of interactions in scenarios;
• The initial states and the final states of scenarios;
• The content of scenarios with respect to the goals they are coupled to; and
• The content of scenarios with respect to their level of context.

The six following subsections present the content guidelines CG₁ to CG₉ dealing respectively with these key points.

Scenario general content: single flow of interactions

The content guideline CG₁ tells the scenario author that every scenario illustrates one possible manner to achieve a goal.

The guideline emphasizes that several scenarios can illustrate the same goal in different manners. These scenarios correspond to alternative ways to achieve the goal. Such an alternative can be normal (the goal is achieved in the final state) or exceptional (the goal is not achieved). They can contain similar flows of actions, as well as variations in the actions they contain, alternative constraints, different initial states, or even events that appear in different places of the alternative scenarios.

This guideline leads the scenario author to

• Consider the goals his/her scenarios should describe;
• Separate the different ways to achieve these goals;
• Associate ways to achieve a goal to a different scenario; and thus,
• Describe each scenario as a single flow of interactions.

This guideline helps to remove several typical errors and difficulties. For example, it eliminates the merging of different behaviors in the same scenario. The separation of two behaviors into different scenarios results in easier scenario writing, better organization of the scenario collection, and easier reading of each individual scenario. Furthermore, it becomes easier to track the system features among Use Cases when each scenario that composes them describes a specific flow.

Using the content guideline CG₁, the scenario author may ask himself several questions: What is a goal? What are interactions? What are flows of interactions? What difference is there between a normal and an exceptional scenario? Content guidelines CG₂ to CG₉ assist the scenario author in answering these questions.

Scenario interaction contents

The content guideline CG₂ tells the scenario author that every interaction description includes an interaction name, two agents and one object.

The templates proposed in CG₂ identify what to put in a complete interaction description. These templates correspond to common linguistic structures of scenarios.

Using the content guideline CG₂ for each of the interactions described in scenarios, the scenario author is made to identify

• The name of the interaction description,
• The parameter of the interaction,
• Whether the agents appear explicitly in the interaction description or not, and
• The direction of the interaction by distinguishing the ‘from’ agent and the ‘to’ agent.

These guidelines can be proposed to the scenario authors under the textual form proposed here. However, templates can also be easily implemented in a tool forcing the user to use the templates in a systematic way. Although this guiding strategy has the advantage of concentrating the task on the correct interaction templates, the other guidelines must also be recalled to the author to ensure that the way he/she fills-in the template entries still fits to the expected style and content.

Content of scenario flows of actions

The content guidelines CG₃ to CG₆ tell the scenario author the precise meaning of the four kinds of flows that can be met in a scenario.

The four guidelines emphasize the relationships between scenario interactions defined by the conceptual scenario model. Their templates define the content of correct descriptions of the scenario flows of actions.

In applying the content guidelines CG₃ to CG₆ the scenario author has to

• Identify in which kind of flow an interaction is involved,
• If the flow of actions is a constraint or a repetition, identify its conditions,
• Identify how the flow of actions relates an interaction to the remaining flow of actions of the scenario, and
• Express explicitly the flow of actions using one of the proposed templates.

The same remark made on CG₂ applies here. These content guidelines being presented under the form of template, their implementation in a tool is easy, and might exempt the scenario author from referring back constantly to an excessive number of guidelines. However, the other style and content guidelines still have to be applied systematically, and must thus be recalled to the scenario author in a complementary way.

Scenario initial and final states

The purpose of the content guideline CG₇ is to tell the scenario author that his/her scenarios should describe initial and final states, as defined earlier in the general guidelines.

Content guidelines CG₁ to CG₇ deal with the content of scenarios, as defined by the scenario model presented through the general guidelines. In contrast, CG₈ and CG₉ help the scenario author to deal with the external properties of scenarios. These two guidelines are dealt with in the following two subsections.

Scenario content with respect to goals

The purpose of guideline CG₈ is to tell the scenario author that scenarios are related to the goals they are coupled to.

Using the content guideline CG₈, the scenario author has to

• Identify the goal related to the scenario,
• Identify whether the scenario is normal or exceptional,
• Determine the scenario interactions that participate in the description of success and failure in goal achievement respectively.

Scenario content with respect to level of context

The content guideline CG₉ brings to the attention of the scenario author the precise meaning that is given by the conceptual scenario model to the level of context of scenarios.

Using CG₉, the scenario author has to identify

• The context level of the scenario
• Whether the scenario interactions are homogeneously described at this level of context or not.

A scenario that does not respect CG₉ mixes up levels of context.

Short Example

Let's go back to the example of the credit management system project. A group of salesmen of the company that owns the system was asked to participate in a half-day workshop in which they would elicit their initial requirements with Use Case models. As they were asked to, the salesmen brainstormed, generated creative ideas, discussed them, and produced a large list of Use Cases. The guidelines they received were rather about creativity than on Use Case naming conventions. Therefore, they defined the Use Case names their own way.

The Use Cases resulting from the creativity workshop had names such as “marketing”, “offer”, “contract”, or “signature”. The CRUD (Create-Read-Update-Delete) pattern had been avoided (Lilly 2000), but it was very unlikely that stakeholders other than the salesmen themselves would know what “offer” meant, that the “contract” Use Case was in fact the one by which they meant that they expected the system to help them to “Define a contract proposal by amending a contract model according to an offer”, and that the “signature” Use Case name meant that the system should be able to “Define a contract from a contract proposal at the moment of its signature”. In fact, it was even very probable that these names were so ambiguous that different salesmen would themselves have put different scenarios under the same Use Case.

At this point in the Use Case authoring activity, the name being the first (and only) attribute defined by stakeholders, it is important that a good understanding of the rest of the Use Case can be easily intuited from it. The adequate guideline is the general guideline GG₁. The guideline shows that the initial Use Case names are not adequately stated, as they are just composed of single names or single verbs. On the contrary, Use Case names such as “Prepare an offer” or “Define a contract from a contract proposal at the moment of its signature” are complex predicates structured with a verb and one or several complements. These statements are much less ambiguous and can be further completed with additional complements.

Let us now have a look on the main scenario initially written for the “Prepare an offer” Use Case (the one initially named “Offer”). The triggering event is the arrival of credit request from a customer to a salesman. In the initial situation of this Use Case, the customer and a salesman have already discussed and the salesman has checked informally that the credit request is founded (it corresponds to the acquisition of a vehicle). The customer can be new or he could have had a credit in the past. Customers are also legally entitled to request a credit even if they already have one (in France, the legal constraint relates to a maximum debt rate). An initial draft of the scenario body was written as follows:

However, this scenario violates several guidelines. It contains ambiguities, terminological inconsistencies, over and under specifications, it mixes up multiple levels of abstractions, multiple-paths hiding other scenarios, descriptions of actions that do not contribute to the design or evaluation of the system, ambiguities about the role of the system, and so on. Therefore, it was decided to train the salesmen in scenario authoring, and to provide them with authoring guidelines as presented above.

The first sentence in the scenario

is a typical case of over-specification in which the author enters into the details of how an action is performed. The problem is threefold: first, the mix up in levels of abstractions makes the reading of the scenario more complicated; this is against guideline SG9. Second, by trying to write how the system interaction is performed, the author makes a hidden design decision (the action shall be implemented using a form). Last, the author enters into one detail of the interaction, but doesn't describe it completely. These issues raise a number of questions: What is the “contract proposal” form composed of? What are the fields used? Are there different interactions or just an “OK” button? and so on. The scenario we are dealing with is an interaction scenario. It is not the place for answering these questions. On the contrary, the guidelines SG2, SG4, and CG2 suggest to write the interaction as simply as possible, for example in the form “The salesman enters the customer information in the system”. This interaction can be further refined in the form of a lower level Use Case that can be authored and analyzed later, on which design decisions can explicitly be made, and which can be completely materialized with a concrete scenario.

In addition to this, the sentence also shows a case of terminology inconsistency in which the “corresponding data” becomes just another name for the “customer information”. In the rest of the scenario, the “customer information” becomes the “entered information”, and the “customer” becomes the “client”.

The inconsistent use of terminology clearly shows that the style guideline SG8 was not applied. The guideline makes explicit that there should be no synonyms and no homonyms in scenarios. This, of course raises the question whether “contracts” and “customer contracts” are the same (or are customer contracts one specific kind of contract?). Similarly, what is a “preliminary contract offer” with respect to a “contract proposal”? Maybe the ambiguity was not embarrassing, if the salesmen perfectly knew their terminology and agreed on it when they wrote the scenario. However, once the team became heterogeneous with people from different origins (e.g. salesmen from different countries, and from different subsidiaries of the company), the difficulty became much more present, and even raised important discussions before arriving to a compromise on which term to use for which kind of business object. In this kind of situation, it is recommended to build and assess a dictionary of the business domain before even authoring the Use Cases. The terms used in the Use Cases can then refer to it, and be changed according to the evolution of this dictionary.

Later in the scenario, the constraint

shows a typical case of ambiguous statement due to the use of pronouns combined with a negation, an incomplete action description, and an implicit constraint. This is respectively against guidelines SG9 (no ambiguous terms!), SG1 (write complete actions at the active voice, present tense) SG3 (no modal verb such as “can”, no negation!), and CG5 (explicit constraints!). A better application of the guidelines would have lead to a less ambiguous sentence such as “if there is no account for the customer, then the system creates a new customer account”.

The fifth sentence in the scenario

is again a case of over-specification due to a complete mix-up in the levels of details. The action achieved by the risk administrator is in fact to “complete the risk evaluation in the system”. This is how the action should be described at the interaction level, as required by the guidelines. How this is done, and with what information, is a concern of importance, but it should be described in a more detailed scenario. The other way round, where the risk administrator gets his/her information about customers is information that does not involve any interaction with the system. Therefore, the clause “uses the result of its enquiry at the bank consortium” should be removed from the sentence. The corresponding activity can be defined as part of the role of the risk administrator on the business level.

This sentence poses another issue as it mentions the “system's risk evaluation” as an object whereas the scenario doesn't tell when the system evaluates risk, or even if it performs this activity at all. The role of the system is ambiguous and should be clarified, either by renaming the object, or by showing where this object comes from, how the system creates it, and so on.

The scenario ends with two sentences that show a complete mix up of multiple variations of a Use Case in a single scenario.

First, the Use Case model makes it clear that each scenario in a Use Case corresponds to a unique flow of actions. This is materialized by guidelines GG₄, SG₆, CG₁, and CG₅ that require avoiding the “IF-THEN-ELSE” pattern, which is typical of this error. The error can easily be detected in the scenario through the use of the term “Otherwise”. This part of the sentence should be removed from the scenario; an alternative scenario can be identified in the Use Case.

These two sentences also violate the guideline SG₁₀ according to which the terms used to define the Use Case and scenario meta model shouldn't be used in scenarios themselves. This guideline is violated twice through the two occurrences of the term “scenario”. In the first sentence, the impact is low as it just adds unnecessary information to the scenario. In the second sentence “… and the scenario starts again”, the impact is more important as it hides the fact that there are several situations in which offers can be prepared: for the first time, and based on a counter proposal. The scenario that corresponds to the first case is the one at hand. The scenario that corresponds to the second case should be written separately with its specific initial states, final states, and flows of actions.

COMPARISONS

The Use Case authoring guidelines presented in this chapter aim only to improve your Use Case-based Requirements-Engineering processes. Of course, better guidelines could be created; such better guidelines could be more synthetic, more adapted to your stakeholders' skills, or even more efficient with respect to your purpose and project context. We encourage you to write down your own guidelines; not only to teach your colleagues how you expect Use Cases to be authored, but also to show that you have yourself adopted a documented, repeatable, and optimized way of working.

Several empirical experiments have been undertaken with various kinds of stakeholders to evaluate the effectiveness of Use Case authoring guidelines under different conditions (see for example Achour-Salinesi et al 1999, Cox and Phalp 2000). The results of these experiments indicate that: (i) if only suggested to the authors, the authoring guidelines improve slightly the overall quality of the Use Case prose, (ii) the different guidelines work differently and with different levels of efficiency, and (iii) Use Cases and scenarios are never entirely correctly written. A major lesson is therefore that

• Use Cases should always be checked and corrected after they have been written,
• Each guideline has a specific impact on Use Case quality, and
• Applying Use Case authoring guidelines is a learning process rather than an activity of going forth and back from the guidelines to the Use Cases.

Since the improvements due to guidelines are most often specific, it is necessary to combine guidelines (e.g. Firesmith 2002, Wirfs-Brock and Schwartz 2002) to obtain a general improvement of the overall Use Case quality. However, experience and experiments also showed that having too many guidelines increases the complexity of the authoring activity, and finally decreases their effectiveness. The number and quality of Use Case authoring guidelines can be considered correct when their application has become transparent to the Use Case authors.

Other Use Case authoring guidelines can be found in the literature. For example, Cox and Phalp (2001) propose simplified guidelines that they compare to some of the guidelines proposed here. There is also an enormous quantity of guidelines available on the web. They go from commented templates (Wiegers 2003), to complete descriptions of Use Case authoring processes (Cockburn 2001), including lists of pitfalls that should be avoided when authoring Use Cases (Lilly 2000).

KEYWORDS

Use Cases

CREWS

L'Ecritoire

Use Case Templates

Use Case Authoring

Writing Guidelines

Scenarios

REFERENCES

Ben Achour-Salinesi, C., Rolland, C., Maiden, N., and Souveyet, C., Guiding use case authoring: results of an empirical study, Proceedings of RE '99, International Conference on Requirements Engineering, Limerick Ireland, June 1999.

Cockburn, A., Writing Effective Use Cases, Addison-Wesley, 2001.

Cox, K. and Phalp, K., Replicating the CREWS use case authoring guidelines experiment, Journal of Empirical Software Engineering, 5(3), 245–267, 2000.

Firesmith, D., Use Case Modeling Guidelines, August 2002, http://www.donald-firesmith.com/

Lilly, S., How to avoid use-case pitfalls, Software Development Magazine, 40–44, 2000.

Rolland, C., Souveyet, C., and Ben Achour-Salinesi, C., Guiding goal modelling using scenarios, IEEE Transactions on Software Engineering, Special Issue on Scenario Management, 24(12), 1055–1071, 1998.

Wiegers, K.E., Software Requirements, 3rd ed., Microsoft Press, 2003. The Use Case template is available at http://www.processimpact.com/process_assets/use_case_template.doc

Wirfs-Brock, R.J. and Schwartz, J.A., The art of writing use cases, Tutorial Presented at OOPSLA'02: The ACM SIGPLAN Conference on Object-Oriented Programming, Systems, Languages, and Applications, Seattle WA, November 2002.

Scenario Plus, http://www.scenarioplus.org.uk, website providing use case editing, metrics, and Cockburn-based guidelines tools, 1997–2003.

RECOMMENDED READING

(Self-reference) the guidelines presented in this chapter were developed in the context of the ESPRIT fundamental research project CREWS. The initial purpose of the guidelines was to obtain Use Cases and scenarios that could be analyzed by automated support, so as to discover new goals in a goal model. Other papers on this topic and others by the CREWS team can be downloaded from URL http://sunsite.informatik.rwthaachen.de/CREWS/

(Lilly 2000) gives a brief report of her experience of bad Use Case authoring and its impact on IT projects.

(Cockburn 2002) provides a complete book about Use Case authoring. Cockburn's vision of what Use Cases are, how to use them in Requirements Engineering and how they complements other models such as goal models has been determining in the Use Case community. His process description and Use Case authoring guidelines will provide you with a more detailed discussion than is possible here.