Delivering Valuable Software through Use Case Driven Development

November 14, 2020

Blog > Architecture, Development, Management | Valentina Cupać

Why are we building software?

At the end of the day, we’re delivering software to satisfy user needs so that the user can achieve some goals which are valuable to them. But how do we know what the user actually needs? The short answer is, we don’t truly know. However, we have techniques to help us approximate what the user needs, and then by delivering software iteratively we can validate whether we’re meeting user needs (and then make adjustments).

This was one of the key motivations for agile development – after all, the first principle of the Agile manifesto is “Our highest priority is to satisfy the customer through early and continuous delivery of valuable software.” The key words are: early, continuous and valuable.

Previously I wrote about the importance of understanding the business domain when building software (https://www.linkedin.com/pulse/3-ways-increase-productivity-software-development-teams-cupa%C4%87/). This is a follow up article which helps us understand the business domain through the eyes of the user.

User Stories

User stories are a tool which helps us satisfy the customer and deliver value, by describing, from the user perspective, WHAT the user the user wants to do (the tasks that the user wants to perform) and WHY (the goal they are trying to achieve). User stories are a one sentence specification written in natural business language, so that they are understandable by the business side. This avoids long documentation which no one wants to read, and it helps to ensure good understanding between the Customer and the Product Owner.

Template for writing a user story is:

“As a [user], I want [perform some task], so that I can [achieve some goal].”

An example is:

“As a customer, I want to make an order for pizza, so that I can eat pizza without having to go to the pizza shop.”

For further references, see https://www.atlassian.com/agile/project-management/user-stories

It should also be noted that a user story should fit within a single sprint. If it doesn’t then it becomes an epic and needs to be broken down further into multiple user stories. This is crucial to help us achieve earlier delivery.

Acceptance Criteria

As you’ve noticed above – the user story is very high level, informal, and doesn’t tell us any details – instead, it just opens up many questions and ambiguities. This is why Acceptance Criteria comes in handy, in drilling down the User Story the user story becomes more clearer. Acceptance Criteria specifies what we’re trying to achieve – the conditions under which a user story is fulfilled. Whereas Definition of Done (DOD) is a general criteria which has to be satisfied by all User Stories, Acceptance Criteria specifies conditions for a specific User Story – nonetheless, most must be satisfied.

Acceptance Criteria helps add feature scope details, sets scope boundaries, it describes not only positive scenarios but also negative scenarios. When Acceptance Criteria is well defined, then it clarifies understanding, enables better estimations and streamlines acceptance testing. It makes it clearer to developers what they need to develop, as well as more clearer to testers what they need to test.

The two most common formats for writing Acceptance Criteria is: scenario-oriented and rule-oriented (though other custom formats may also be used if appropriate). The scenario-oriented way is helpful for defining scenarios for manual and automated testing. The rule-oriented way is useful in cases where scenario-oriented way doesn’t naturally fit, for example in specifying some system functionality or system constraints.

Scenario-oriented Acceptance Criteria

The form for scenario-oriented Acceptance Criteria follows the [Given / When / Then] format from Behavior Driven Development (BDD).

Examples are as follows:

Scenario: Customer orders pizza during pizza shop working hours

GIVEN I’m a logged in customer
WHEN it’s between 09:00 – 21:00, I select some pizza AND click on confirm order
THEN the system shows the message “you have successfully made an order” and places the order

Scenario: Customer orders pizza outside of pizza shop working hours

GIVEN I’m a logged in customer
WHEN it’s between 21:01 – 08:59, I select some pizza AND click on confirm order
THEN the system shows the message “Sorry we’re not working now”

Rule-oriented Acceptance Criteria

Rule-oriented Acceptance Criteria can be used to specify certain attributes for system functionality or anything else which is not easily specified by the scenario-oriented way.

The format here is just a series of bullet points.

Examples are:

User cannot select more than 3 pizzas
Button “Confirm order” is in the top right corner next to the “User Profile” image (see UI mockup)
Order cannot be confirmed if there is some quantity < 1
Acknow email is sent to the user after completing the order
Response time should be less than 300ms (otherwise if it takes longer, then there should be a message to the user “Please wait some more…”)

Use Cases

In the above section, we went through writing User Stories and Acceptance Criteria. The user Story was an informal description of a user’s intended action and the goal that the user is trying to achieve, whereas Acceptance Criteria added some more details to “flesh out” the User Story.

Use Cases help describe to developers HOW the system should behave (aka the functional requirements of the system) in a way that is more formalized than User Stories. Thus, unlike User Stories, Use Cases tend to go into detail regarding functional behaviour., and are useful in modelling processes.

Template for a Use Case is:

Title: Title of the use case (sentence)
Description: Short description of the user case (paragraph)
Actor(s): Who is involved in the use case
Pre-condition: What must be satisfied before the use case starts
Basic flow: Lists the steps of the main flow, indicating the interactions between the actors (e.g. user does A, then system does B, then user does C, then system does D), this is the primary flow for the use case
Alternative flows: Indicates the various things an actor could do, but which don’t result in error states
Exception flows: indicates the various things an actor could do, which result in error states

Example is:

Title: Order Pizza
Description: Customer can order pizza via the online pizza shop
Actors: Customer
Pre-conditions: Customer is logged in
Main path:
- 1. Customer selects pizza
- 2. Customer clicks on the Shopping Cart
- 3. System shows the pizzas and quantity 1 for each pizza
- 4. Customer clicks on “Confirm order”
- 5. System shows success message
- 6. System sends email notification
Alternate paths:
- Customer clicks on Cancel instead of Confirm Order; System goes back to pizza screen; Customer can repeat process
- Customer manually edits the quantities ordered
Exception paths:
- Customer inputs quantity < 1; System disables the “Confirm Order” button; System displays an error message “Quantity must be greater than 1”
- Customer clicks the “Confirm Order” button during non-working hours; System shows an error message “The shop is closed, please try again at 09:00 the next day”

Here are some articles for further reading regarding use cases:

https://www.bridging-the-gap.com/what-is-a-use-case/

https://www.visual-paradigm.com/guide/uml-unified-modeling-language/what-is-use-case-diagram/

User Stories vs Use Cases

User Stories and Use Cases have the same goal but they are not interchangeable. They both convey information about users/actors and the goals that those users/actors are trying to accomplish. But the point where they differ is as follows:

User Stories are strongly associated with Agile, whereas Use Cases date much further back (Use Cases were introduced by Ivar Jacobson over 30 years ago)
User Stories are less detailed (and informal), and Use Cases are more detailed (and formalized)
User Stories lead to more questions, whereas Use Cases are more comprehensive
User Stories are focused on the end result and benefit, whereas Use Cases describe more how the system will act and describes all possible ways how the user and system may interact

It’s a cost-benefit trade-off whether to use just User Stories or to use them in Conjunction with Use Cases.

For really simple interactions, perhaps User Stories could be enough
But in cases of more complex processes, then using User Stories could open up many gaps for development, lead to many back-and-forth meetings, result in ambiguities, and in mismatches between development and testing, so this is where investing for example an hour in writing a Use Case might later save you days of re-work (since after all, writing the Use Case is generally much less costly than re-working development)

For further reading about User Stories and Use Cases:

https://www.visual-paradigm.com/guide/agile-software-development/user-story-vs-use-case

https://www.seguetech.com/user-stories-vs-use-cases-pros-cons-agile-development/

Documenting Requirements in JIRA vs Confluence

Some teams use JIRA for writing User Stories, whereby a JIRA ticket is used both for specifying the User Story as well as for managing the status of the ticket.

Other teams write all requirements in Confluence (for example, using the Product Requirements template in Confluence or custom templates) which contains the User Stories and all associated details, whereas JIRA is used just for managing statuses.

I’ve used both these ways on various projects, though for the last several years I tend to prefer Confluence for all requirements documentation (User Stories and Use Cases) with tickets generated in JIRA. That way, all the requirements documentation is centralized in Confluence, easy to read to see the big picture and also can be exported for other stakeholders.

Use Case Driven Architecture, Development and Testing

Thinking from the perspective of the user leads us to “pragmatic” architectural and design decisions.

Use Case Driven Design – Helps developers focus on users and their interactions with the system
Hexagonal Architecture / Clean Architecture – Promotes use cases as first-class citizens within the architecture, whereby the use cases are the entry point into the system
API Driven Development – Fits in well with Use Case Driven approach because it means that API endpoints should be modelled in order to satisfy use cases
Task Driven UI – Helps frontend developers be focused on the use cases, the tasks that the user needs to accomplish
Acceptance Test Driven Design – Helps QA Engineers write automated tests from the perspective of the user, to test the use cases