How Difficult Is It to Document Good Requirements?

In this blog post, I’ll share ten of the worst and most egregious examples of requirements documentation that still haunt me.


Because so many team members will rely on these lists to do their tasks successfully, writing requirements is one of the most crucial components of product development.

As a result, requirements writing should be of very high quality, and bad documentation will have a detrimental impact on the team’s performance.

In this essay, I examine the ten worst requirements I’ve encountered in my years of expertise.

#1 – “The system must have good usability”
#2 – “Response time should be less than X seconds”
#3 – “Round-the-clock availability”
#4 – “The system shall work just like the previous one, but on a new platform”
#5 – “The system has to be bug-free”
#6 – “Reporting”
#7 – “Make it accessible”
#8 – “X cannot change”
#9 – “Easy to use”
#10 – “It has to be robust”

#1 – “The system must have good usability”

This one always gets me.

Of course, a system should be easy to use!

That is something that every tester and developer is aware of. But who is it supposed to ‘feel good’ to?

Describe the user group(s) and the level of knowledge they are anticipated to have.

The vagueness and absence of objective criteria are recurring themes in this collection of cringe-inducing regulations.

The time it takes to accomplish a specific action is an example of quantifiable criterion.

“A customer support representative should be able to enter three concerns in less than 15 minutes,” is a better approach to state this requirement. This is quite quantifiable.

Setting standards is another method to make usability measurable.

If your firm has a published standard, you might declare that the system should be designed in accordance with it.

Of course, just because a standard states that the OK button should be located to the right of the Cancel button does not mean that the system is usable; the only way to know for sure is to conduct usability testing.

#2 – “Response time should be less than X seconds”

That’s understandable; we all want our software to be lightning fast. But under what circumstances do you anticipate a two-second response time?

Is this figure based on inherent variations in the system’s response time, and does it pertain to a specific product functionality, or does the PO expect a two-second response time across the board, including crucial elements of the system?

This type of requirement is doubly nefarious because it is skillfully veiled by the inclusion of an objective amount that lends it validity. However, if you dig a little deeper, the requirement crumbles under the weight of sheer ridiculousness.

Any measurement should be offered in the context of a specific situation. For instance, consider the search feature or adding a new customer to the database. You must also specify how it should be measured, for as on a standardized desktop behind the firewall or over ADSL on a slower PC.

Consider inherent variations in the system, such as the fact that many banks are overburdened on salary payment day. Do you have any differences on other dates, such as the start of a new month or year?

“[Response Time] Is Doubly Devious Because It Is Cleverly Disguised by An Objective Amount That Gives It the Appearance of Legitimacy.”

#3 – “Round-the-clock availability”

What do you mean? Do you mean 24 hours a day, 7 days a week, 365 days a year And who is going to foot the bill?

Neglecting the time, money, and energy expenditures associated with developing and testing the client’s needs is a major blunder that will almost certainly result in tragedy.

In these situations, the team must play the role of counselor, gently alerting the client to any evident flaws in their needs.

In some cases, such as with internet banks, 24 hours a day, 7 days a week is a realistic need. However, this need is frequently too expensive to be deemed practicable.

Either you must determine whether or not this requirement is genuinely critical, or you must negotiate an agreement with the stakeholder.

In the long run, reaching a compromise on the stakeholder’s original demands and ‘optimizing’ (a wonderful phrase to use during negotiation!) their requirements to better meet the project’s scope and budget will save the team a lot of time and effort.

#4 – “The system shall work just like the previous one, but on a new platform”

This is a common blunder.

“But don’t add ‘these features,’ because we don’t use them anymore,” is usually the implication. “We trust you to take into account all of our undocumented concerns throughout the years about some of the characteristics we despise,” they add.

Because needs have changed, you must undertake proper requirements management again when developing a system using other methodologies. A new platform also has advantages and disadvantages that must be examined. When the platform is altered, features that previously operated in one way will no longer work.

Making a rapid prototype of the system employing the new technology would be a more cost-effective approach.

To uncover the gaps between the prototype and the final product, conduct workshops and behavioral research on real users. This is also a wonderful chance to go through new features and potential limitations of the new platform.

#5 – “The system has to be bug-free”

This demonstrates an immature approach to quality assurance and customer and supplier interaction.

Early on, you must build a proper change management and testing procedure that involves both parties with clearly defined responsibilities.

Documentation, help systems, and end-user training are all topics that must be discussed in early projects.

“Early on, establish a proper change management and testing process that includes both parties with clearly defined responsibilities.”

#6 – “Reporting”

One of the most critical responsibilities of software, regardless of business, is to crunch through complex data and produce actionable insights, preferably with plenty of flashy visualizations that emphasize trends and patterns in a system.

That’s why everyone who wants new software for their company comes to you and asks for the capacity to “produce reports.”

The issue here, as with most of the other problematic requirements we’ve discussed, isn’t what’s being sought, but what’s being left out of the request. There is no guidance on how comprehensive a report should be, which metrics should be included, or who is permitted to create and read the report.

#7 – “Make it accessible”

The final point conveniently leads us to our next nightmarish requirement.

Accessibility can be broad or narrow, but in any case, a clear profile of the people who will be able to interact with the system is required in order to design relevant test cases for the scenarios that are likely to occur.

Furthermore, accessibility is not always a binary yes/no situation. Even if the system’s doors are wide open for everyone to interact with it, some people may have access to features that other do not.

This graduated accessibility is inextricably tied to the roles that different classes of users play, which in turn impacts the behaviors that they are permitted to perform.

#8 – “X cannot change”

Extending the concept of multiple degrees of privileges for different users brings me to another blunder that drives teams into a tailspin.

When clients claim that certain features of the system can’t be changed, your first retort should be something along the lines of, “Who can’t modify X?”

Frequently, you’ll realize that their original request was merely a code for the fact that certain users are unable to update specific components of the system without the authorization of a supervisor or other users with high-level privileges.

“Most of the time, you’ll find that the original requirement is a shortened version of the truth.”

#9 – “Easy to use”

Clients’ proclivity for using abbreviated language when communicating requirements reveals the root reason of the existence of bad requirements in the first place.

I completely agree with testers who have stated on several internet forums that weak requirements are actually miscommunicated requirements.

Then it’s our job to help bring clarity and practical significance to what our clients tell us by thoughtfully investigating the reasons behind their claims.

Making software “simple to use” is a typical request that necessitates more development in order to put into effect.

  • What, in the client’s opinion, makes software simple?
  • Is it having a short time for end-users to learn how to use the finished product?
  • What significance does this have for the client and the business they represent?

These inquiries all assist in determining the appropriate importance of a requirement, which would otherwise be one of those ordinary requests you receive on a regular basis.

#10 – “It has to be robust”

Finally, this gem of a phrase concludes our list of dreadful standards.

The issue here isn’t the requirement in and of itself. Although robust software is a desirable quality, that statement lacks a quantitative component to correlate the tester’s perspective with the client’s desired outcome.

A quick and straightforward technique to beef up the information provided by the client is to translate robustness into the metrics that are commonly used to give an indication of this quality.

In this situation, asking about the goal time to restart after a failure, for example, aids the software’s alignment with the client’s practical requirements.

“A Quantitative Element Must Be Included to Align the Tester’s Perception with The Client’s Desired Outcome.”

  • The ambiguity and absence of objective criteria are two prevalent characteristics of cringe-inducing requirements.
  • Any measurement should be offered in the context of a specific situation.
  • Because needs have changed, you must undertake proper requirements management again when developing a system using other methodologies.
  • Early on, establish a proper change management and testing procedure that includes both parties with clear roles.
  • Most of the time, you’ll find that the initial need is a shortened version of the truth.
  • A quantitative component is required to align the tester’s view with the client’s desired outcome.

For more info:

Also Read: