Why write detailed requirements for software development?
The devil is in the details
Often what you need seems simple enough at a first look. With software development, it will inevitably take more time and effort to complete than initially expected. Small mistakes often lead to significant misunderstandings and problems later on in the project.
This article is intended to help the following three groups of people:
The CEOs and decision makers
This article is useful to CEOs to understand why their business needs well-formed and relevant detailed requirements. You will also see what the benefits will be from making the investment and the consequences of not making them.
Department managers and senior user roles
If you want to deliver better results or simply work smarter and more efficiently you will need to change how you and your team works. Once you have read this article you will be able to communicate what changes you need in a clear and precise manner.
You can use this article to help your clients understand why they will benefit from investing time in thinking through and defining their requirements.
We call detailed requirements "user scenarios and acceptance tests" or US & AT. You may also hear them referred to as “user stories”.
It seemed simple enough to start with
Have you seen this play out in your company or project? You made a few shortcuts when you defined your business requirements because they seemed obvious enough. Later down the line your developers are not delivering the features you want. Everyone on the team, yourself included, is growing more and more frustrated. What’s more, the costs are through the roof and you have very little, if anything, to show for it.
Unfortunately, there are many who recognize the above scenario. Could all of this have been avoided? And if you are currently living through this, is there anything that can be done now. It is useful to recognize the consequences of badly written requirements. In order to understand the benefits of writing detailed requirements at the right time and it is useful to recognize the consequences of badly written ones.
I understand you, based on what I think you are saying
It is difficult to get others to really understand what you are saying and asking for. It is one of the primary problems of being a human. Try though you might to come across clearly, people will often perceive and understand you in an altogether different way.
How many fights between couples have started with one person misinterpreting the other? How often have you had a complete disconnect with someone you know well? People often do not realize that they are not coming across the way they think they are. If this can happen at home or with close friends, then consider how much greater the risk is with an acquaintance and new team member.
Misunderstandings from poor requirement management are compounded when...
Success or failure is your choice
The hassle, frustration, and pain that result from poor requirement development and management are things I do not wish on anyone. These are some of the issues that originate from poorly written requirements:
There are additional consequences that arise from these problems:
Who is responsible?
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 result.
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?
Getting great results from your business
Digitizing 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 digitizing 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 prioritize 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.
Why would you want well-formed detailed requirements?
As a CEO I want well-formed detail requirements in the form of user scenarios and acceptance tests so that:
As a department manager I want well-formed detail requirements in the form of user scenarios and acceptance tests so that:
As a project manager I want well-formed detail requirements in the form of user scenarios and acceptance tests so that:
As the development team we want well-formed detail requirements in the form of user scenarios and acceptance tests so that:
Business analysts are skilled at helping you develop and manage detailed requirements
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:
- 1Identify business needs.
- 2Write and manage requirements in order to define the required capability of the business.
- 3Prioritizing the work that needs to be done to best deliver value to the business.
How to create your user scenarios and acceptance tests
Defining (writing) US&ATs takes time and effort and can be expensive if not done effectively. If you do not have a good structure and process, you will quickly become bogged down and lose focus. To give you structure we use the capability breakdown structure and the build road map. Using these two tools you are able to focus on what components to write US&AT’s for and in what order.
User scenarios and acceptance tests are developed during the design process. This is done within the scope set by the high level requirements documentation and the capability breakdown structure.
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.
Writing user scenarios and acceptance tests that are easy to understand
But how do you write US & ATs that are specific and easily understood? It takes practice, like everything else in life. However, if you follow the following patterns you will be off to a good start:
User scenario pattern
"As a (role) I want/need (add ability you need) so that (describe what the benefit of this ability is)."
Acceptance test patterns
You can use either of the two patterns below to describe your acceptance tests. Bear in mind that one user scenario will normally have two or more acceptance tests.
"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)."
"Given (one scenario and related conditions) when (specify the action/event) then (expected outcome)."
How does the US & AT pattern support the characteristics?
A well-formed US & AT has the following characteristics and patterns:
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.
Epic is a technical term for a grouping of US & AT that combine to create a component. In an e-store the shopping basket would be classified as an epic. The features, such as being able to remove items from the basket, would require individual US & ATs.
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 apply their technical knowledge to decide how best to deliver that capability.
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.
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:
The acceptance tests describe how you will validate that the software does what you need it to do. They have four very important functions:
- 1They enable the development team to understand how you will use the required capability so they can test what they build.
- 2They enable you to validate that you have the capability that you asked for.
- 3They prevent scope creep.
- 4They are the definition of “done” so that you can measure progress.
Keeping it under control
Well defined requirements have a direct impact on your software development investment. If you have well-formed and thought through user scenarios and acceptance tests you will have much better control over the six most important interdependent variables of software development.
This, in turn, means that your software project is significantly more likely to be successful.
Turning things around can seem like an overwhelming task if your project is already struggling due to the complications of poorly written requirements. However, there is still help to be had. Qualified business analysts and consultants can help you sort out your US & ATs to get your project moving in the right direction again.
Start smart with defining and understanding what capability you need for your business change.
Of course, if you have any further questions about writing user scenarios and acceptance tests you can always contact us. We are happy to help.