- We first write a top-to-bottom description of one easy to understand and fairly typical scenario in which the primary actor’s goal is delivered and all stakeholders’ interests are satisfied.
- This is the main success scenario.
Ex: "Well, actually, there is a little complication. When such-and-such occurs, what really happens is ...".
- A condition under which the scenario runs.
- A a goal to achieve.
- A set of action steps.
- An end condition.
- A possible set of extensions, written as scenario fragments.
-
Contract between Stakeholders with Interests
- an interaction between two actors ("Customer enters address")
- a validation step to protect an interest of a stakeholder, ("System validate PIN code")
- an internal change to satisfy a stakeholder ("System deducts amount from balance")
- an interaction between two actors ("Customer enters address")
-
Each action step is written to show a simple, active action. I liken it to describing a soccer
match: Person 1 kicks ball to person 2. Person 2 dribbles ball. Person 2 kicks ball to person 3.
- a simple action in which one actor accomplishes a task or passes information to another actor.
- Most of the time, the timing can be omitted, since steps generally follow one after the other.
- Subject ... verb... direct object... prepositional phrase.
Ex: The system ... deducts ... the amount ... from the account balance.
- nota do marcelo, essa é uma estrutura SVO (Sujeito-Verbo-Objeto)
- At each step one actor "has the ball". That actor is going to be the subject of the sentence, the first actor named, probably as the first or second word in the sentence. The "ball" is the message and data that gets passed from actor to actor.
- The actor with the ball will do one of three things: kick to him/her/itself, kick it to someone else, clean off the mud. About half of the time, the step ends with another actor having the ball. Ask yourself, "At the end of the sentence, now who has the ball?"
- Write the use case from a bird's eye point of view.
Ex: The customer puts in the ATM card and PIN.
The system deducts the amount from the account balance.
or
Customer: puts in the ATM card and PIN.
System: deducts the amount from the account balance.
- Note that the information content the same in both styles.
- The mistake of choosing very small steps shows up in the length of the use case. If a use case has 13 or 17 steps, it is quite likely that the sentences are not moving the goal forward very much. The use case is easier to read and clearer and contains the same essential information when we merge those small steps to get one that moves the process distinctly forward. I rarely encounter a wellwritten use case with more than 9 steps in the main success scenario.
- Describing the user’s movements in operating the system’s user interface is one of the more common and severe mistakes, and is related to writing goals at too low a level.
- Dialog descriptions makes the requirements document worse in three ways
- Longer documents are harder to read, and more expensive to maintain.
- The dialog being described is probably not really a requirement, it is probably just how the writer imagines the user interface design at that moment.
- The dialog is brittle, in the sense that small changes in the design of the system will invalidate the writing.
- In the requirements document, we are interested in is the semantic description of the interface, one that announces the intent of the user is, and gives just a summary of the information that is passed from one actor to another. Ex:
Before:
1. System asks for name.
2. User enters name.
3. System prompts for address.
4. User enters address.
5. User clicks ’OK’.
6. System presents user’s profile.
After:
1. User enters name and address.
2. System presents user’s profile.
- Ivar Jacobson has described a step in a use case as representing a transaction:
1 The primary actor sends request and data to the system.
2 The system validates the request and the data.
3 The system alters its internal state.
4 The system replies to the actor with the result.
- You can write each piece as a separate action step, or combine them in various ways, up to putting all four into a single action step.
Which is best depends on how complicated each separate piece is and where the natural breaks occur in the processing.
Ex:
- The customer enters the order number.
- The system detects that it matches the winning number of the month.
- The system registers the user and order number as this month's winner, sends an email to the sales manager, congratulates the customer and gives them instructions on how to collect the prize.
- Often people write that the system checks the condition. This is not a good action verb.
It does not move the process distinctly forward, it is not really the goal,
and it leaves open what the result of the check is.
- Why is the system checking the condition? Answer:
It is establishing or validating or ensuring something.
Those are good goalachieving action verbs to use.
So replace
"The system checks whether the password is correct"
with
"The system verifies that the password is correct."
- Let the presence of the word if trigger you to recall this guideline. Any time you see "if the (condition)... then...",
look at the sentence before it. It is likely to say checks. Replace the first sentence with validates,
and make the second sentence a simple action with no if.
Before:
2. The system checks whether the password is correct
3. If it is, the system presents the available actions for the user.
After:
2. The system validate that the password is correct
3. The system presents the available actions for the user.
- Notice that the writing in the second case describes the scenario succeeding. It also triggers the reader to ask at step 2,
"But what if the password is not valid?" The reader will turn to the extensions section and look for the extension starting with "Password is not valid".
It gives the use case a consistent rhythm that makes the use case easy to read and review.
- Feel free to put in the timing, but only when you need to. Usually the timing is obvious and need not be mentioned.
- We cannot write, "User hits FETCH button, at which time the system fetches the data from system B." That would have us describing the user interface details.
- We can use two steps:
4. User signals to the system to fetch data from system B.
5. The system fetches the background data from system B."
- With this small shift in writing, we indicate that the user controls the timing,
that the ball passes from the user to the SuD to system B, and show the responsibilities of all three systems.
The details of how the user initiates the action is unspecified, as it should be.
- On occasion, we want to mark that some steps can be repeated. Here again, we are lucky that we are writing in plain prose,
as opposed to using a programming formalism.
- If there is only one step being repeated, you can put the repetition right into the step:
Before:
"The user selects one or more products."
After:
"The user searches through various product catalogs until he finds the one he wants to use."
- If several steps are being repeated, you can write the repetition before or after the repeating steps.
Ex: 1. Customer supplies either account identifier or name and address.
2. System brings up the customer's preference information.
3. User selects a item to buy, marks it for purchase.
4. System adds the item to the customer's "shopping cart".
Customer repeats steps 3-4 until indicating that he/she is done.
5. Customer purchases the items in the shopping cart (see use case xxx).
- A variant of "Do steps x-y until condition" is "Steps x-y can happen in any order." I find it works well to put this before the steps affected.
- Step numbers clarify the steps and give places to refer to in the extensions section. They are,
however, harder to maintain. Without good tools to automatically renumber when we insert or delete steps,
it becomes tedious renumbering steps yet again for the same use case.
- The teams I have visited who have tried both consistently selected numbered sentences over paragraphs.
So numbered sentences have become my standard way of writing. Other people are simply happy writing in paragraph form and have no interest in switching.
- Paragraphs are the default suggestion in both the casual template and the Rational Unified Process template