RULE 7: Describe ALL the transactions
A use case, as the name implies, describes the usage of the system from the point of view of some beneficiary (our Actor). It is NOT (as I seem to spend my whole life telling people) is just the system function, organised as some sort of graphical ‘sub-routine’. This means the use case description must include the expected behaviour of the actors as well as the expected behaviour of the system.
This can sometimes appear counter-intuitive to use case newcomers. If the use cases define the functional behaviour of the system, then surely we can’t impose requirements on our users (the actors)?
In fact, this is not the case (and stop calling me Shirley).
The use case describes what we (or, more correctly, our customers) would like to happen when they use the system. It describes the typical interactions between stakeholder and system, such that the stakeholder achieves their goal. If the goal of the use case is beneficial to the stakeholder (see Rule 5) then the stakeholder has compelling reasons to behave as we describe in the use case. In other words, if the stakeholder wants the end result, they should comply with the behaviour described in the use case.
For example, if the system requests some information from the actor it is reasonable to expect them to respond with the information. In effect we are imposing requirements on the stakeholder (“when the system requests information, you shall respond”). Of course, there’s nothing to stop the obtuse user from not responding, walking away, or doing any number of other bizarre and inexplicable things; but these behaviours are a fantastic source of exceptional flows. This approach moves the use case writer away from describing system functions and instead focuses them on the transactions between the stakeholder and the system.
The use case description defines the system behaviour as a sequence of atomic transactions between the actors and the system. Atomic is used in the sense of indivisible. This means that, in the context of the problem domain the transaction cannot be broken down into smaller transactions. (See also: Rule 9). There are four basic transactions, and the use case description will be made up of sequences of these transactions:
- The actor supplies information to the system. Information could be an event (such as the trigger event) or data; or both.
- The system does some work. Remember to describe the results of the work, not how the result is achieved
- The system supplies information to the actor. Again, this could be requests for information, output signals, etc.
- The actor does some work. As mentioned above this is unenforceable, but reasonable behaviour on the part of the actor.
The fundamental transactions of a use case
Writing style
I suggest writing each transaction in a simple, semi-formal, declarative style. For transactions involving information exchange into or out of the system (that is, ‘Actor supplies information’; ‘The system supplies information to the actor’) I use the following style:
[Source] [Action] [Object] [Target]
For example: “The Navigator supplies the Airfield Altitude to the NAV/WAS system”
| Source: | The Navigator |
| Action: | Supplies |
| Object: | Airfield Altitude |
| Target: | NAV/WAS System |
For descriptions of work being done (either by the system or by the actor) I use the following form:
[Subject] [Action] [Object] [Constraint]
For example: “The ARS rewinds the hose at 5 ft/s +/- 0.5 ft/s”
| Subject: | The ARS |
| Action: | Rewinds |
| Object: | The Hose |
| Constraint: | 5 ft/s +/-0.5 ft/s |
If a transaction contains more than 3 punctuation marks it’s probably too complicated and should be restructured to make its meaning better understood.
Weak phrases
Weak phrases make for comfortable reading of a use case but are apt to cause uncertainty and leave room for multiple interpretations.
Use of phrases such as “adequate” and “as appropriate” indicate that what is required is either defined elsewhere or, worse, that the requirement is open to subjective interpretation. Phrases such as “but not limited to” and “as a minimum” suggest that the requirement hasn’t yet been fully defined.
Typical weak phrases include:
- As applicable
- As appropriate
- But not limited to…
- Effective
- Normal
- Timely
- Minimize
- Maximize
- Rapid
- User-friendly
- Easy
- Sufficient
- Adequate
- Quick
The truth is, in general engineers have poor writing skills. By providing a framework for how use cases should be written you are limiting the scope for ambiguity, wooliness and inconsistency.
He specialises in C++, UML, software modelling, Systems Engineering and process development.
- Practice makes perfect, part 3 – Idiomatic kata - February 27, 2020
- Practice makes perfect, part 2– foundation kata - February 13, 2020
- Practice makes perfect, part 1 – Code kata - January 30, 2020
Glennan is an embedded systems and software engineer with over 20 years experience, mostly in high-integrity systems for the defence and aerospace industry.
He specialises in C++, UML, software modelling, Systems Engineering and process development.
