How to deal with poorly written requirements

Last post 03:10 pm August 3, 2021
by Garry Taylor
6 replies
09:53 pm July 30, 2021

Hi all,

I am a member of a software development team who is struggling with work due to poorly written requirements by the PO. It is causing some stories to bounce between development and testing. It is written in the usual format of given, when then. The problem with this format is that it does not provide the context nor the background, especially when we have new Devs joining the team. The business rules are quite complex and we have zero documentation. Refinement sessions sometimes help especially if it is recorded. I would appreciate your help in finding a format as a template for writing detailed requirements, or any advice to help overcome the problem.

Thanks in advance

10:33 pm July 30, 2021

I would appreciate your help in finding a format as a template for writing detailed requirements, or any advice to help overcome the problem.

Does the PO, or anyone, actually know what the detailed requirements are?

Perhaps Scrum is being used precisely because the challenge is ill-defined and the work is expected to be emergent.

10:35 pm July 30, 2021

Rather than try to put it all down in writing, has the team tried a Three Amigo/Amiga's approach? Since it can be challenging to put an abstract requirement into words, having the Product Owner, Developers and testers have conversations can be beneficial. Even the ubiquitous user story was meant as a promise to have a conversation. 

Specification by example (SBE) is another approach your team could experiment with. SBE is a collaborative technique which captures requirements by illustrating real-world examples. If you google the term you should find plenty of examples.

Impact Mapping might be nice workshop to have your Scrum Master facilitate to give everyone better insights and to augment your Product Backlog. Here is a great article:

 Breaking your Product Backlog items down into smaller items might also be something to try.

06:31 am July 31, 2021

Thanks all. Does the Impact Mapping technique also work for a set of requirements for software support service. As such we do not have a product per se, but we use SAAS, (Software as a Service) . The requests come from all departments e.g. sales, deployment, shipping etc.. so we have a varied and complex business rules. I just cannot visualize how to use SBE when we don't have an end product, 

09:57 am July 31, 2021

A couple of things stand out to me.

The first is the use of the "given when then" format. Who chose this format to express the work that needs to be done? There are plenty of other options out there, and Scrum doesn't mandate or even suggest any of them. When getting to more complex business rules, there are even visual methods like flow charts, decision tables or decision trees, and state tables or state diagrams that can be used to express those rules. I would recommend strongly against a specific format, since my experience tells me that people who mandate strict formats for their Product Backlog Items focus more on achieving the format than expressing the necessary information to understand, plan, and implement the Item.

The second is that the Product Owner is responsible for the "poorly written requirements". The Product Owner represents all of the different stakeholder groups outside the team and holds the vision for how the product will evolve to satisfy their needs, but the whole team is responsible for ensuring that the Product Backlog Items are ready for a Sprint.

I'd recommend using a Sprint Retrospective (if not time earlier) to take a look at how the team is expressing Product Backlog Items and carrying out refinement. Find the information that the team needs to be able to successfully plan and implement a PBI and then how to get that information represented.

08:27 am August 2, 2021

Thank you all for the useful insight. I will be using the retro to voice my concerns over the issues we are having with requirements. 

Perhaps we should not focus on what template we should use for the reason you mentioned. The intention was to figure out of any if any system/framework incorporates story context/background. I have identified that the problem is to do with the team not fully understanding the business rules as it is a newly formed team.  Trying to help, I thought the format may force to add more details before the story gets executed.

03:10 pm August 3, 2021

stories to bounce between development and testing

this feels like a Scrum But to me...

Nothing should be bouncing and the Team is responsible for the delivery of the PBI from development to release. If this is going to a dedicated testing team, then bouncing back, the testers and the devs should be working together (pair programming, Screen share, stat on the same seat). Testers shouldn't have to wait for devs to start testing, and developers shouldn't be blocked by testers. What do they know that the developer does not?

I find that building a definition of done (DoD) for the PBI helps during refinement. This is something the team creates, reviews and agrees to (developers, testers, QA, Ops). Does the specification allow all the agreed DoD to be fulfilled, if not then break the problem down into their smaller parts and find out why. If it doesn't meet the DoD then it's not ready to add to the Sprint.

Another common issue is that the requirements are telling you a solution but hiding the underlining problem.

Spec: Make the "Email" button blue on Monday's

WHY x 5

Just because a spec is simple, doesn't mean it fits DoD. The team must understand the reason behind the request and turn solutions back into their original problem.

Problem: On a Monday, sales must send welcome emails to new clients

Here, the development team are able to create a better solution, rather than making the "Email" button stand out, this can be turned into an automated process and remove the button.

Given, When, Then can help but I like... Give, When, Then, Because

As stated above, Scrum does not state how to do this and I feel there is no template that can help but a DoD checklist is useful. It is down to what works with the team. Having a good PO that works with the team is vital... having a good Scrum Master to educate the PO is also vital. Get these two people working in harmony and the specs will flow :) 

Remember that as long as your team improve with every Sprint, you're heading in the right direction.…