Software development best practice: Good requirements lead to great architecture

As an agile software development team, you may frequently find that your delivery dates are wrong. It seems that requirements have changed and therefore caused the delay, or there were hidden complexities in the feature.

What if the reason isn’t that the requirements changed but instead there was a misalignment between what was understood to be delivered vs. what was actually required to be delivered.

Let’s unpack

To start, one must understand that there is no-one to blame for this misalignment. It is everyone’s responsibility to participate in the gathering and refinement of requirements – that includes developers, designers, business and testers, etc.

But wait, we do work together, yet we miss our deadlines.

This is where a well-defined process can help your team achieve optimal requirements gathering.

With great requirements comes great understanding, which leads to better estimations and software architecture and in turn fewer bugs and missing features.

Case study

A typical planning session might go like this:

First, a requirement is brought up in the planning session:
“Okay, we need to allow our users to sign in using biometrics.”

Sounds pretty doable, let’s create a story!

Story

As a user
I want to be able to log in using my preferred biometric option
So that I don’t have to type in my username and password

Great, now we have a very basic story that describes vaguely what we expect a user to be able to do. We can improve upon this using behaviour-driven development (BDD) principles. Let’s add an acceptance criterion to the story using the Given-When-Then format.

Acceptance criteria

Given a user
When the user authenticates with her biometrics
Then the user is logged in

This is an example of a story with an acceptance criterion that shows the big picture, but it lacks any sort of important details. Having the big picture in mind is a good starting point, but this is also the final step for many teams. Without digging deeper into the story, the team takes a risk of being misaligned on the required effort.

We can solve this by starting to eliminate assumptions, and we eliminate assumptions by asking questions. With the new knowledge obtained, we can evolve the basic requirement into a more detailed explanation of what is actually required.

To come up with questions, think about scenarios a user might encounter. For example:
“What should happen if the user doesn’t have any biometrics registered on the device?”

This got the UX designer thinking that perhaps it might be a good idea to inform the users that they can only use this feature if they have biometric data. The team also realised that perhaps there is more to this user story. A user can have biometrics enabled or disabled on the app.

These discussions should evolve the story, so let’s improve on our initial big picture story:

Story 1

As a user with biometric data
I want to be able to log in using my preferred biometric option
So that I don’t have to type in my username and password
And so that I am logged into the app.

Acceptance criteria (Scenario — Has biometric data)

Given the user has biometric data
And the user has opted to use biometric authentication
When the user tries to log in
Then the user should be given the option to log in with her biometrics.

Given the user has biometric data
And the user has not yet opted to use biometric authentication
When the user tries to log in
Then an alert should display informing the user that biometric authentication can be enabled in the settings menu when the user has logged in
And after the user accepts the alert, should be allowed to sign in using her username & password combination.

These two acceptance criteria now cover both scenarios for a user that has biometric data on the device, but we also need to cater for users that don’t have any biometric data on their device.

Story 2

As a user without biometric data
I want to be able to log in using my username and password
So that I am logged into the app.

Acceptance criteria (Scenario — has no biometric data)

Given the user has no biometric data
When the user tries to log in
Then an alert should display informing the user that biometric authentication is only available if the user has biometrics data registered on the device
And after the user accepts the alert should be allowed to sign in using her username & password combination.

It’s also always a good idea to think about the failure case, and ask questions such as:
“What should happen if the biometric authentication fails to authenticate the user?”

This will lead to new details in the story where we will need to explain how we handle this case. A good idea might be to fall back to username and password. This can be written in the acceptance criteria of the new story.

So, in essence, put yourself in the shoes of the user, think about the different scenarios the user can find herself in and ask questions about the different scenarios.

Important: Create these scenarios and acceptance criteria while the team is together discussing it. Don’t discuss it and do not put anything down on digital paper!

Okay, so far so good

After the previous exercise, the entire team learned together about the edge cases, the scope and the size of the requirement. Before asking these questions, the feature had hidden complexities and if these complexities appear in the middle of development, they can have massive time-consuming consequences.

But we can go further, this is where the development team take these well-written stories and start drafting use cases.

Use cases

These are recipes set up by the developers, for the developers to translate these stories into software requirements. These are focused on the business logic and are intended to be more technical and will help when designing the architecture for the new feature.

Biometric login use case

Data (input):
1. URL
2. User biometric authentication

Primary course (happy path):
1. Unlock auth token from secure storage
2. System validates auth token
3. System delivers successful authentication

Invalid biometric authentication — error course (sad path):
1. System delivers “failed authentication” error

No registered biometric data:
1. System delivers “no biometric data” error

Biometrics not enabled on app:
1. System delivers “biometrics not enabled” error

As you can see, we’ve listed what we expect the biometric login use case will require and what we expect its outputs will be for both success and failure cases. This would help your team deliver better quality code, since decisions made during development will be much better informed.

We don’t go into detail about what the UI will have to show once it receives what the system delivers, because that’s covered in the stories. But you and your team are more than welcome to break it down further.

The idea is to keep refining the requirements until your team is confident it understands what needs to be done. With this understanding, your team can make more accurate estimations and delivery dates.

This will also assist teams wanting to experiment with test-driven Development development (TDD). The use cases we created will help you write tests to fulfil.

And now — you are ready to jump in!

To expand your mind on this topic, read more about:
1. Behaviour-driven development
2. Test-driven development

A special thanks to essential developer for being a great resource of learning.

Planning to build an app? 

Try our free software development calculator to maximise your ROI.

Request for Access to Information

The following forms are available to download with regards to request for access to information:

REQUEST FOR ACCESS TO RECORD

OUTCOME OF REQUEST AND OF FEES PAYABLE

INTERNAL APPEAL FORM