Why write detailed requirements for software development?

by Don Lowe
CEO

September 13, 2018
Reading Time: 11 minutes

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.

Development teams

You can use this article to help your clients understand why they will benefit from investing time in thinking through and defining their requirements.

MVP resources for idea validation

​Terminology

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.

Forbytes talking team communication software development project

Misunderstandings from poor requirement management are compounded when...

  • ​People leave the team and you need to bring new team members up to speed
  • ​Changes need to be made and communicated to all concerned 
  • ​Changes to requirements are made but not everyone is aware that they have been approved
  • stop
    ​Requirements are not clear, and the actual development is done several weeks or months after the requirements are discussed.

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:

Forbytes illustration why write detailed requirements for software development programmer leaving due to bad requirements
  • ​Lack of clarity over what was really asked for, resulting in friction and arguments.
  • ​Inability to validate that the development team has delivered what was requested.
  • ​Constantly changing requirements.
  • stop
    Very difficult, or impossible, to estimate the effort needed to deliver working code, due to the way the requirements are formulated.
  • stop
    ​Developers wasting time having to re-write functionality, features, and whole components as requirements change.
  • stop
    ​The team is unable to keep to delivery dates on work packages ​due to the extra work ​caused by the changing requirements.
  • stop
    ​The compounding of small delays results in the project delivery dates constantly changing.
  • stop
    ​Poor quality requirements inevitably leads to poor quality solutions.

There are additional consequences that arise from these problems:

  • ​Staff churn in the development team. People leave the team as it is not fun to work on the project anymore, resulting in increased recruitment and education costs.
  • ​Escalating cost due to re-work and delays.
  • ​Loss of revenue generation from improved solutions.
  • stop
    ​Loss of customers as they find it easier to do business with the competition.
  • stop
    Bankruptcy.

​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.

Forbytes illustration digitizing your business hairdresser stressed phone ringing
Forbytes illustration digitizing your business hairdresser digital booking schedule solution

​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:

  • The development team can estimate the effort required and the expected costs to deliver the solution.
  • ​We can agree on the objectives and delivery of the project.
  • ​There is a realistic means to measure progress and keep me informed about any changes to the delivery date.
  • stop
    I can have confidence in the project management that they have control of the project at all times, and that we are getting what we need as a business.

​As a department manager I want well-formed detail requirements in the form of user scenarios and acceptance tests so that:

  • ​We can remove any ambiguity in what we need early on in the project.
  • I have a means of validating that what my team is asking for is delivered.
  • ​The development team can give us reasonably accurate estimates as to when we will be able to work with the new solutions. This allows us to plan future activities that are dependent on the solution being in place.

​As a project manager I want well-formed detail requirements in the form of user scenarios and acceptance tests so that:

  • ​I, together with the team, can identify constraints or issues that we had not previously identified and take action to address them before they have an impact on the project.
  • ​I can quickly put an end to misunderstandings, so ​the team can focus on working towards delivery rather than arguing​.
  • ​I can measure the progress of ​the work being done on a daily basis.

​As the development team we want well-formed detail requirements in the form of user scenarios and acceptance tests so that:

  • ​We know what the definition of 'done' is for each US & AT before we start writing any code.
  • ​We have requirements written in a consistent way. This will make it easier for different team members to come to the same understanding as to what is being asked for across the whole section.
  • ​We can identify missing requirements and take action early on.
  • stop
    ​Individuals can give feedback and clarify anything that they are not sure about.
  • stop
    ​We can discuss within the team how best to deliver the US & AT.
  • stop
    ​We can measure progress of the work being done and estimate delivery dates on a daily basis.
  • stop
    ​We can validate that we have the right skill sets within the team to deliver what the business needs.

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.

Forbytes illustration business analyst manager helping programmer find right information paper pile requirements user scenario acceptance tests

Business analysts work with department managers and members of the business departments to:

  • 1
    ​Identify business needs.
  • 2
    ​Write and manage requirements in order to define the required capability of the business.
  • 3
    ​Prioritizing 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.

Forbytes project development process diagram user scenario acceptance tests article

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.

Forbytes illustrations programmer manager roadmap building road to organize business

​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.

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)."

Option 2:

"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:

  • ​Understandable
  • ​Independent
  • ​Negotiable
  • stop
    ​Valuable
  • stop
    ​​Can be estimated for effort
  • stop
    Small (preferably less than 5 days to develop)
  • stop
    ​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. 
MVP resources for idea validation

​Terminology

​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.

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 apply 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. 

developing your MVP into a full solution with Forbytes

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.
  • stop
    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:

  • 1
    They enable the development team to understand how you will use the required capability so they can test what they build.
  • 2
    They enable you to validate that you have the capability that you asked for.
  • 3
    They prevent scope creep.
  • 4
    They 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.

  • 1
    ​Cost
  • 2
    Scope
  • 3
    ​Time
  • 4
    ​Quality
  • 5
    ​Benefits
  • 6
    ​Risks
Forbytes time risk quality cost benefits scope pyramid user scenarios and acceptance tests managing your business user stories article illustration

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.