Proper software requirements 101

I am not a requirement engineer and do not write software requirements on daily basis. This story is written in software developers perspective.

Software requirements are the basis of all proper development work. You need them if you want to succeed. Unfortunately most of the requirements out there are incomplete or written, if at all, very badly leaving too many open questions for the developer actually doing the design and implementation. That is why every project should have good requirements that tell exactly what needs to implemented not forgetting error situations.

Requirements vs user stories

User stories are used to define the software on very coarse level. Mostly I’ve seen them written in format: As a [type of user], I want [some goal] so that [some reason]. This is, in my opinion, a good way to write user stories. Still one should not mix this with software requirements. Requirements are products that are based on user stories. Most likely a single user story will, and should be, split into multiple requirements.

LanguagePhoto by Raj Eiamworakul on Unsplash

The requirements should always be written in language that everyone, already in the project, or joining later on, can understand. Even your company is located in, let’s say Norway, you cannot be sure if the next hire will be a foreigner or the whole development is outsourced to some other country. Having your specifications, requirements and other information in Norwegian at that point will either require the new hire to learn a new language or all the documents needs to be translated in another language. Anyways it will mean a lot of work for someone.

I’ve seen this happen in many projects. Most of the time the documents were just translated to English. This might work but there can be hiccups there as all languages do not work the same and cannot be translated from word to word. Think about using a translated requirements document as source for your implementation. What if the translation is wrong? Who will get the blame of implementing things against the requirements — is it you, the translator or someone else? That is why in general you should use English in all specification and requirements work.

Content and formatting

Software requirements should be self-explanatory and easily understandable. In my opinion a good way to start creating requirements is to think what it MUST do, what it SHOULD do and what it CAN do. Using just one of these words in your requirement can make a lot of difference in the final outcome.

There are multiple types of software requirements. While most of the requirements are so called “functional requirements” that define specific behavior or functionality, you should never forget to also write down “non-functional requirements” for the software. These requirements define criterion that can be used to judge the operation of a system. Example of non-functional requirement for web application could be “The login page must respond in no less than 50ms”.

Readability is also one important thing in the software requirements and you should pay close attention to the formatting of the requirements document. Bad formatting is off-putting and makes it hard to concentrate on the content. You should always test the readability of the document before publishing it.

You should also think about the target audience of your requirements. They are not only used by the software architects and engineers but also test engineers and project management. With good requirements it’s easier to plan and execute tests as well as plan the whole project’s timeline.

Example

Let’s imagine you are working for ACME Ltd. as a only developer for a new project to create a babysitter robot. The company’s robotics team has put up a demonstrator robot which can be used for testing the software. At this point you don’t have to think how the robot will be configured (how many kids, where do they sleep, if they use diaper etc.) or how the robot can understand what the kids say. As a developer you get the following requirements:

• Robot starts to take care of kids when parent presses a button
• Robot feeds the kids when they are hungry
• Robot changes diaper when it’s full
• Robot puts the kids to sleep at 8PM if parents are not home
• If there is a problem, the robot sends a message to parent
• Robot recharges itself in the meantime

“A robot named Pepper holding an iPad” by Alex Knight on Unsplash

As you can see, these requirements are not self-explanatory. What if the startup fails? What button should the parent press? When does the robot know when a kid is hungry or diaper is full? Are there any prioritization between the tasks? How does the robot know if parents are home? Can the robot stop an ongoing task to go recharge itself? These are only few questions that arise from these requirements.

Now let’s think again how we could improve and extend these requirements:

• Robot must start when parent presses power button marked with (|). During the startup the robot must do a self-test (what it contains is another requirement). If the self-test fails, robot must peep three times and shutdown. After the robot has started it must start taking care of the kids.
• Robot should ask each kid every 1 hour if they are hungry until 8PM. If the answer is yes, it should give some [configured food] from [configured place] to the kid. If there is another task ongoing, the robot must ask the question after the task is completed even it’s over 30 minutes from the previous question.
• Robot should ask each kid every 30 minutes if their diaper is full until 8PM. If the answer is yes, it must stop all other tasks and change the diaper. If there is another task ongoing, the robot must ask the question after the task is completed even it’s over 30 minutes from the previous question.
• Robot must take each kid to their own bed at 8PM starting from the smallest kid. Before taking kid to bed the robot must execute the diaper query and act according to the answer. When the kid is in bed, the robot can play one of the following songs: ‘Itsy bitsy spider’, ‘Frosty the snowman’ or ‘Soft kitty’.
• If a kid hasn’t eaten in 2 hours or a kid is shouting constantly over 15 minutes, the robot must inform the parent by sending an SMS to [configured number].
• If the robot does not have any tasks to do, it must go to docking station to reload if the battery level is below 30%, it should go if the battery level is below 60% and it can go even the battery level is over 60%.

These requirements are still not complete and are missing information but at least I would have some idea how to start working with the software design based on these.

Refinement and deviations

Requirements hardly ever hit the goal with their first version. It’s very important to also spend time to refine and fine down the requirements while the development is ongoing. Development might find some deviations which might cause a change to the original requirement. Deviation can be for example if the robot in the previous chapter fails the self-test it only peeps twice because programming language used only allows calling same function twice. This kind of, while absurd, limitation should be either documented to the customer or the original requirement needs to be changed depending who is requesting this feature.

If the original requirements leave too many open questions, the refinement process can be very exhausting and time consuming. When writing software requirements try to come up as good first version as possible — in the long run it will save time from you and from the whole development team.

Further reading

Here are some good books that you might want to read if you are working with software requirements:

• Software Requirements 2 2nd Edition
• Software Requirements Engineering
• Writing Effective Use Cases (Crystal Series for Software Development)
• Agile Software Requirements: Lean Requirements Practices for Teams, Programs, and the Enterprise

About me

I am Heikki Hellgren, Software Expert and technology enthusiast working at Elektrobit Automotive. My interests are in software construction, tools, automatic testing and all the new and cool stuff like AI and autonomous driving. You can follow me on Medium and Twitter. Also you can check out my website for more information.

Proper software requirements 101 was originally published in Hacker Noon on Medium, where people are continuing the conversation by highlighting and responding to this story.