Not All Stories Are Told at Bedtime – Documenting Use Cases

Systems Engineer, Alex shares more insights into documenting use cases in his latest post... 

Having reached the point where we have identified our use cases and represented them on one or more diagram; the time has come for the real work to begin.

The use case name, use case diagrams and use case briefs / descriptions provide a high-level abstract view of what the system must  (or will) do.  Behind each use case is a structure that describes the use case in more detail.  This structure identifies the specific behaviours and interactions that occur between the actor and the system with the use case’s flow of events.

The structure contains the following fields:

·         Description - Describing the role and purpose of the use case

·         Trigger  -   What starts the use case executing

·         Pre-conditions  -  What must be true before the use case executes

·         Post conditions  -  What is true after the use case executes

·         Primary scenario  -  The activities the system performs

·         Alternate scenarios   -  Alternative flow of events, variations in behaviour

The purpose of this structure is to capture what has to be done by each use case to accomplish the functionality.  We must consider the basic functionality, any alternatives, error conditions, anything that must be true before the use case executes and anything that is true on exiting the use case. Let’s examine these further.

A trigger specifies the event that starts the use case executing, for example, a cash machine wakes up when the customer inserts his/her card.  Often the trigger is the first step in the flow of events / scenario(s).

Pre-conditions describe the state of the system before the use case runs.  What must be true in order for the use case to execute. Pre-conditions apply to the state of the system, not the outside environment.  A common mistake is to write pre-conditions that that are often or sometimes true, but not always. Examples of pre-conditions are: “The user is logged on”, “The target has been selected” etc.

Post conditions describe the state of the system as result of the use case executing.  A use case can either fail or succeed and therefore it is difficult to write post conditions that hold true in both situations.  

Pre and post conditions can help identify dependencies between use cases.  Remember, they are states the system is in either before or after a use case executes. While pre-conditions can be identified early on, the post conditions will only become apparent after the scenarios have been written which I will discuss in my next post.