So, do you know how to build a software system for your client? (part 2 - the Requirements Domain)
Tags: softwareengineering, agile, requirements, specifications
Published: 2019-07-11 19:32:15

---
title: So, do you know how to build a software system for your client? (part 2 - the Requirements Domain)
published: true
cover_image: https://thepracticaldev.s3.amazonaws.com/i/7oj6reqsgjuu3wqwaiae.jpg
description: Managing Requirements and creating Specifications
tags: Software_Engineering, agile, requirements, specifications
---

# The Requirements Domain

In every knowledge domain, be it medicine, manufacturing or software development, we need to have a mental model of the domain entities involved and their interactions, before we can start thinking about providing solutions in that area. A Domain Model is a representation of all the important entities, activities and their relationships in a specific Domain.

So, for instance, in the Pizza-making Domain (one of my favourites) we would expect to find entities such as Dough, Toppings, Restaurant, Delivery Person, etc. Similarly, in the Requirements Domain we'd expect to find entities and relationships that help us conceptualise requirements. 

The entities of the Requirements Domain are:

* Stakeholders
* Business Goals
* Capabilities
* Features


## Stakeholders and Actors

A *Stakeholder* is someone who derives value, benefits from or influences our system. An *Actor* is a Stakeholder who interacts with our system, either directly or indirectly. All Actors are Stakeholders, but a Stakeholder is not necessarily an Actor


![](https://thepracticaldev.s3.amazonaws.com/i/qwfmja9908wsbx7nh505.jpg)

There is a small, but important sub-set of Stakeholders which is the set difference between Stakeholders and Actors. We call these 'Non-acting Stakeholders'. These would usually be people like Directors, Business Owners, Enterprise Architects or Senior Managers. They will have a stake in the system and they will likely make decisions that influence the system, but don't expect to see them sitting down in front of a screen and using the system any time soon.


Actors may be divided into two categories:
1. Primary Actors interact with system directly through a UI or API in order to achieve a specific goal.
2. Secondary Actors are actors that the system needs assistance from in order to achieve the Primary Actor’s goal.


## Business Goals

Goals that benefit the Stakeholders. Business Goals are usually defined by Non-acting Stakeholders, such as Directors, Senior Managers, etc. The Business Goal's incentive and ultimate outcome should ultimately fall under one of these categories:

* Increasing revenue
* Reducing costs
* Protecting revenue
* Avoiding future costs

A useful technique for determining a Business Goal's incentive is the 5 Whys technique. If after the 5 questions the answer isn't one of the above, then you should seriously question the value this Goal adds to the Business. 

*Example*: Reward loyal customers
Why? So that returning customers can feel valued and also save some money 
Why? So that customers keep returning more often 
Why? So that they spend more money on our products (increase revenue)


<b>Tip:</b> Good Business Goals add value to Stakeholders by specifying goals tangential or extrinsic to the system's inherent abilities and functionality. For instance,  'I want customers to buy books' is not a valid goal for an online book-store.  'I want customers to buy more books from us than competitor X' is  better, though it still lacks a strategic aspect. Speaking of which...

### Strategic goals  are the best goals

The best Business Goals are the ones that aren't too abstract, nor too specific, the ones that outline strategy but not tactics. For instance, the goal  of  "Rewarding loyal customers" can be framed as "Increase sales by rewarding loyal customers".  "Increasing sales" is the end-goal and "rewarding loyal customers" is the strategy.  If the goal was simply "Increase sales" or "reduce costs" then it would ultimately fall to whoever happened to implement that goal, a business analyst or -shock, horror- a software developer to determine what the best strategy would be.  The best people to define the strategy behind the goals are the Non-Acting Stakeholders, the directors, business owners and senior managers. 

On the flip-side, should the Goal become something like "Increase sales by rewarding loyal customers by giving them free gift-bags if they spend over $500 in a single transaction"  then we are mixing strategy with tactics.  This can be a Bad Thing, as creating tactics requires a level of domain, system and architectural knowledge that is usually lacking in Non-Acting Stakeholders (and I'm saying this in the best possible way). For example, the director or sales manager specifying the 'free gift-bag' ploy may not be aware of any logistics or distribution problems in delivering that many gift-bags. Tactics are better developed by other Stakeholder participation and should be captured separately as system Capabilities. 


## Capabilities
A Capability is a system ability that enables the Stakeholders to achieve a Business Goal. Capabilities define *what* the system does but not *how* it does it.  They are high-level, coarse-grained descriptions of activities which enable Stakeholders to derive benefit from the system. A Capability can only be seen within the context of a Business Goal and its associated Stakeholders.

*Examples*

* The HR staff are able to use the system for the on-boarding of new employees
* The Seller can use the system to see real-time stock levels
* End-users are able to log onto the system using their social media accounts

Our ultimate job as System Builders is to deliver Capabilities to our Stakeholders.


## Features

A Feature describes a system behaviour. It's closely associated with a Capability and answers the question "How are we going to deliver this Capability?"

At a minimum, a Feature consists of a feature Title and a Scenario. A Scenario is a look at the Feature's functionality from a specific perspective. So if our Feature is titled 'Withdraw cash from cash-point machine', for instance, we could have Scenarios like 'Cash demand exceeds account balance' or 'Bank note denominations don't match requested amount'.

However, having just a Title and a scenario doesn't help us describe the functionality much. A fully-featured Feature (excuse the pun) will include:  

* **Feature Title**​: a brief description, e.g. Cash Withdrawal
* **User Story**: we use the following template
   
        As an [Actor]
        I want [specific System Behavior]
        So as to achieve [a goal contributing to a Capability]
      
* **Impact**: ​A link to the impact map this Feature relates to (more on these in the next post)
* **Notes**​: any other text that helps the reader better understand the Feature
* **Background**: ​ (if applicable): a common prerequisite
* **Scenarios**​: are written in a structured manner
        
        Given [a Condition]
        When [an Action is invoked]
        Then [an expected Outcome occurs]
       

A valid Feature must have at least one defined Scenario.

To derive Features we have to look at our system Capabilities and answer the question: 'What functionality must we implement to deliver this Capability?'.   

Let's look at the: "The Seller can use the system to see real-time stock levels" Capability. How can we deliver this Capability? We could start by implementing these Features: 


* Feature 1: Integrate Warehouse API to our system
* Feature 2: Create notification mechanism for warehouse stock changes
* Feature 3: Build UI that shows current stock levels

Obviously there will be more Features than these in a real-life system, but hopefully you get the gist: Features are about implementing functionality, Capabilities are about Stakeholder ability to achieve a goal.  We'll be discussing these more in later posts in this series.

## Summary

Stakeholders, Business Goals, Capabilities and Features are fundamental entities in the Requirements and Specification domain. In the next post, we'll explore using these entities to model our system Requirements and derive Specifications with a technique called Impact Mapping.