9 Ways to Write Better System Requirements

9 tips for product owners and business analysts on writing proper requirements.

About 7 years ago, the failure rate (budget & time) of IT projects was a whopping 75%. At the moment it’s still around 50%. Quite painful figures. Very often this is caused by shitty business analysis which results in system requirements that don’t solve the “real” problem. This, while the analysis and requirements are the “backbone” of the system that needs to be built. Therefore, pay some more attention to laying a good foundation. The rest of the development process will run smoother.

One. The perfect format doesn’t exist.
Rule 1: there is no such thing as “the perfect format”. You prepare requirements for a specific target group, and that’s not always the same. Some people write requirements for devs, some write for industrial designers and some might write requirements for a non IT related target group. A format is therefore always customized.
Discuss with your target group what they’re comfortable with. What kind of information do they like to see? What kind of information is unnecessary and can be left out? Prepare a format together and make sure that everyone adheres to it.

Do they want you to include designs? Fine. Do they want you to include the API calls for every feature? Fine! Be flexible, keep communicating and constantly optimize the format. After all, there’s always room for improvement.

Two. Always start with a user story (very old school yes).
Always start with an old trusted user story. By defining a user story, you create clarity in a few sentences about the underlying goal, and your target group will have a better understanding of how to read the requirements.
A good user story describes:

- The actor (user) who performs the action;
- The action to be taken;
- The goal to be achieved with the action.

For example: As a webshop user I want to be able to trace my order so that I can be home at the right time to receive my order.

Keep the user story as basic as possible. Do not address the solution, but only the actor, action and the underlying goal. Try to avoid words such as “and”, “but” and “except”; they only cause confusion and tend to make the user story way too long.

Three. Avoid vague words.
Prepare your requirements without using vague words. For example, “a little”, “sometimes” and “fast” are not measurable nor testable and can cause confusion. Try to formulate as measurably as possible and make sure there is no room for interpretation.

Four. Avoid descriptions of tricky animations.
It’s time-consuming and makes little sense to document tricky animations or moving objects in the design. Ask your designer for GIF’s or videos of the animation so you can show it to your target group. It might also be a good idea to let the designer sit next to the person who is going to carry out the task while doing the corresponding task so they can collaborate effectively.

Five. Stay consistent.
Try to be consistent in your use of words. For example, do not use “shopping cart”, “cart” and “basket” if you always mean the same thing, this causes confusion.

Six. Do not refer to requirements that still have to be specified.
Requirements must be autonomous: complete, independent to handle and easy to read. So do not refer to tasks with requirements that have not yet been worked on, because that can cause someone to get stuck. Moreover, many people find it annoying to always be referred to other requirements.

Seven. Do not just document the happy flow.
Try to document the most crucial scenarios and document the corresponding solutions. What if action X doesn’t work?

Please don’t overdo this.
I’ve seen people trying to squeeze out every possible edge case scenario out of their brains, trying to find a solution for each scenario. They end up meeting with several devs for days which costs them a shit load of money trying to figure out a solution for a scenario that would occur to 1 in 100.000 users.

Eight. Have your system requirements checked by your stakeholders.
Submit your requirements to your stakeholders at an early stage. See if you are all aligned and improve where necessary. Are the business requirements correct and are no assumptions made? Is the underlying problem really solved with the specified requirements? Try to detect errors as early as possible. Because the last thing you want is that the work that has been developed is not fixing the problem.

In the 70s, Barry Boehm came up with “the law of Boehm.” This clearly shows that the repair costs increase exponentially as an error appears later in the development process. The sooner you detect an error, the cheaper it is to correct it.

The law of Boehm

Nine. “Non-functional requirements”, ain’t nobody got time for that
In addition to the functional requirements, it can also be useful to mention the non-functional requirements.

Functional requirements describe what the system must do
Non-functional requirements describe how the system must do the “what.”

You can subdivide the non-functional requirements into different categories:

• Maintainability: The ease with which a product can be maintained in order to achieve a certain goal.
• Usability: the extent to which a product can be used by the specified users.
• Reliability: the extent to which the system continues to function, also during malfunctions
• Efficiency: the extent to which the system performs with the available resources.

Very often, the non-functional requirements are skipped. It‘s obvious that a website must function at least on the best known browsers, and preferably on all browsers and all versions. Nevertheless, it is important to indicate on which browser versions the website should be able to run, and which versions you can omit. After all, it is not realistic to comply with all browser versions.

Here too, the following applies: keep your target group in mind and adapt when needed.

Ten: Here an example of a user story along with some acceptance criteria:

User Story

As a Nike customer
I want the option to change the language on the website
so I can understand the content on the website

Acceptance Criteria

• The language of the website is presented by displaying a flag icon in the header.
• The default language of the website is based on the locale of the customer.
• The customer must be able to change the language by clicking on the flag icon in the header.
• When the customers clicks on the icon, it must trigger a pop-up.
• The available languages must be shown in the pop-up.
• The customer must be able to exit the pop-up by clicking on the “x” icon or by clicking outside the pop-up.
• Yada.
• Yada.

Attachments

• Design.
• Video with animation.

Thank you for reading.