The Perfect Software Requirements to Succeed in Your Project: Tutorial
By: Don Lowe
Tags: Management, Leadership, Software Development, Project Management, Software Requirements

Every CEO or person in charge of a software project needs a strong development team whom they can trust to deliver results. But no less important is having clearly written software requirements so that you can develop and manage your project in an effective way. Writing requirements takes time and effort, but if you have a good structure and a process in place, you won’t lose focus.

The benefits of functional requirements

Some of the benefits of well-formed requirements (“user scenarios and acceptance tests” or US&ATs) are that they are more understandable and clearly state the capability that the customer needs. Well defined requirements have a direct impact on your software development investment. Turning things around can seem like an overwhelming task if your project is already struggling due to the complications of poorly written requirements. The process takes time and effort, but if you have a good structure and a process in place, you won’t lose focus.

The good news is that there are tried and tested processes for communicating, developing and managing requirements. In the software development world, this is a core function of business analysts. Business analysts work with department managers and members of the business departments to:

​Identify business needs.

​Write and manage requirements in order to define the required capability of the business.

​Prioritizing the work that needs to be done to best deliver value to the business.

Why everyone in the team needs to get involved

So, who should take part in the writing of software requirements and in which roles?

Developers are responsible for knowing what a well-formed requirement look and feel like. This is because the requirements are their primary source of direction on how to do their job and deliver results. Providing your client with a quality service means being honest with them and letting them know when they need to clarify what they are asking for. When you are passive and develop code based on poor requirements, you will inevitably be blamed for the poor results.

As a department manager or senior user, you need to make sure that you define your needs in a clear and consistent way. If you do not do this, you make it very difficult or impossible for the development team to deliver what you want and need. This, of course, means that the final product will not be able to help you work more efficiently and deliver better results than before. You also need to ask yourself what the consequences of this will be for you. What can you expect if you are unable to make the expected improvements or reach the goals set by your boss?

As CEOs and business owners, you need to remember that the buck stops with you if your team or supplier takes shortcuts. In order for developers to provide you with a digital solution, they need to understand what your business needs. If you do not ensure that sufficient time, resources, and budget are allocated to this step; what will be the consequences for you personally?

​How to create your user scenarios and acceptance tests

To focus on what components to write US&AT’s for and in what order, we use the capability breakdown structure and the build road map.

You can put time aside to develop all of the US & ATs for the project before starting development, or you can use the concept of rolling wave planning. Rolling wave planning means that you will base your high-level requirements on the capability breakdown structure. Once that is done you will spread out the development of US & AT detailed requirements during the project. This enables you to improve US & ATs for components developed during the later stages of the project, by using the knowledge you gained in the early stages. This system also has the benefit of allowing the development team to start development as soon as they have sufficient information to deliver individual components of the solution.

Defining US & ATs in the same order of the Build Road Map enables you to learn and identify issues that you would not normally think about. This generally results in a much better solution from a business’s perspective.

Create a capability breakdown structure

Every software project starts off as an idea. The mistake many people make is to jump from the idea stage to the development stage before they have given sufficient thought to what the business really needs.

Here are a couple of useful tips for you to follow at this point:

​Focus your discussions on the end capability that you need in order to achieve your objectives.

​Avoid the temptation of discussing features and functions. They will deliver the capability that you need.

​Break down areas of the capability to smaller components that are unique and independent from each other. Some of the functional areas may be five or six levels deep before you have sufficient information to understand what the end result should look like.

User scenario and acceptance test patterns

​User scenario pattern

"As a (role) I want/need (add ability you need) so that (describe what the benefit of this ability is)."

Example:

"As a ​customer, I want to ​​log into my account​​​ so that ​I can see my order history."

​Acceptance test examples

Option 1:

“As a (role) I will (specify the action/event) to confirm that (the ability you asked for) does the following (describe what you expect to happen).”

Example: ​

“As a ​customer, I will ​log into my account to confirm that ​correct login details give me the order history.”

Option 2:

“Given (one scenario and related conditions) when (specify the action/event) then (expected outcome).”

Example:

“​As a customer, I will log into my account to confirm that incorrect login details do not give me the order history.”

Characteristics of well written US&AT

​A well-formed US & AT has the following characteristics and patterns:

​Understandable

​Independent

​Negotiable

​Valuable

Can be estimated for effort

Small (preferably less than 5 days to develop)

Testable

Understandable

The structure of the US & AT pattern makes it easier for people to quickly understand what capability the client wants. It is therefore important that the US & AT describes the capabilities needed, rather than the functions or features. It is the responsibility of the technical team to decide the most appropriate functions or features needed to deliver the business capability.

​Independent

​Each US & AT should focus on independent features within the epic. However, all US & ATs within an epic are interdependent as they aim to build a final joint component. This facilitates change management as you can identify opportunities to make small adjustments.

Negotiable

This refers to how the developer creates the features or functions that deliver the required capability. The product owner decides what business capability is needed and the developer applies their technical knowledge to decide how best to deliver that capability.

​Valuable

Each US & AT must deliver value for the business. You define this value in the third section of the User Scenario construct “As a (role) I want/need (add the ability you need) so that (describe what the benefit of this ability is).”

​Can be estimated for effort

The development team must be able to read both the user scenario and the acceptance tests. From this, they should be able to give a rough estimate of the effort necessary to create the capability.

The US & AT is the primary unit for estimating the effort required and measuring progress on delivery of the project. It is simply not possible to manage project finances and resources effectively without well-formed US & ATs.

​Small

Each US & AT should preferably take less than 5 days to develop. There are several advantages to breaking down your requirements into small understandable deliverables:

It is easier to make and manage changes.

It is easier for others to understand what you need.

You can test early and often to ensure that what is being built is what the business needs.

Progress can be monitored more accurately, which in turn improves financial and resource management.

​Testable

The acceptance tests describe how you will validate that the software does what you need it to do. They have four very important functions:

They enable the development team to understand how you will use the required capability so they can test what they build.

They enable you to validate that you have the capability that you asked for.

They prevent scope creep.

They are the definition of “done” so that you can measure progress.

Getting great results from your business

Digitising is frequently the key to making your business more efficient and completing tedious tasks with a few clicks. Even businesses that are not digital in nature more often than not stand to gain from implementing digital solutions.

It is quite likely that there are aspects of your business that could be made more efficient if you had the right digital tools. These kinds of digital solutions can range from enabling your staff to work smarter and more efficiently, to expanding your market reach.

By investing in digitising your business you may stand to save both time and money, as well as increasing your revenue. If this is the case, should you not prioritise making it easy for the development teams to understand what you want? It is after all the best way to ensure that they deliver what you need quickly and efficiently.