How to write Requirements

Not many engineers get excited about the moment they have to start writing requirements. Writing effective, accurate, and testable requirements is a challenging thing, that takes time and practice to really perfect. Hopefully I can provide some quick, clean, guidance to reference for authoring good requirements.

What is a Requirement

Put simply, a requirement is a single statement that describes a necessary system property, feature, characterization, or usage. While user needs and user stories are written from the perspective of the user and in the language of the user, requirements should be written from the perspective and in the language of the engineer. They are intended to specify "what" the system needs to do in order to meed the needs of stakeholders. They should be stated in quantitative language that can be objectively measured and tested.

A user need may state;

"The user needs the product to support the ability of performing payment transfers to partner devices."

Which may lead to some requirements like;

"The product shall support BLE communications for version 4.0 and beyond."

"The product shall provide controls for users to select which device to send a payment to."

It is important to keep in mind that when creating a requirement it is something the system must do in order to meet its intended use, and it is something the team must test.

Requirement Syntax

Using a structured syntax when writing requirements will create consistency and improve the review process. Using a framework can also help simplify the process of thinking about requirements. One key part included in every requirement is shall. If it states shall then it must be done. Alternatively, should can be used in the event of a suggestion or recommendation. The following is a good structure to work within:

[Noun] shall [Action Verb] [Description] and/or [Conditions]

• Noun - the product being developed or addressed in the requirement
• Action Verb - the action the product will perform
• Description - Describes in more detail about who, what, and where the product will perform this action
• Conditions - Describes the conditions under which the action will take place

Negative Requirements

I want to briefly touch on negative requirements as these can be more common than you would imagine. Negative requirements should not be written as a general rule of thumb. The burden of proof for a negative requirement is far greater, more difficult, and may be impossible. Alternatively, stating the functionality of the system in the positive form; inhibit, perform, or prevent, is a better strategy.

Negative requirement examples:

• The device software shall not fail.
• The software shall not allow database calls when a non-recoverable error is present.

Positive requirement examples:

• The device software shall allow for 96 hours of continuous operation.
• The software shall inhibit database calls after the occurrence of a non-recoverable error.

Requirements of Requirements

The irony, there are requirements for writing a requirement.

Requirements should be unambiguous, verifiable, complete, and non-conflicting. While some aspects of writing a requirement are flexible these four are fundamental and if not met then you have broken requirements.

Everybody likes a checklist right!? If there is one thing you take with you from this post, it should be this checklist.

• Unambiguous, the requirement is concise, consistent and correct. Only one interpretation is possible.
• Verifiable, objectively verifiable whether it be through inspection, demonstration, analysis, or testing.
• Complete, fully stated in one place and there is no missing information.
• Non-conflicting, it doesn't contradict another requirement, it is possible to satisfy all requirements.
• Attainable, or technically feasible, and can be achieved with existing design concepts.
• Rationale provided with reasoning for the need, the assumptions, and relevant design decisions.
• Necessary, if removed a deficiency in the system would occur.
• Implementation free and states "what" and not "how".
• If possible, traced to a higher level user need or requirement (standards, regulation, interface, etc.).

Example Time

Time for everyone's favorite part of the program, lets talk about some examples. Lets use Spotify as an example product and an example feature like, "The user needs the product to support the ability of creating, editing, and deleting playlist." Now most of us understand that Spotify has both a mobile app and a web app, so when I refer to "the system" I am intending to reference both, otherwise I will refer to one specifically in the requirement.

I want to say these are not all encompassing of this feature there may be other requirements like how long a playlist is stored for, limitations on size of playlist, character limitations on playlist name length, ability to download playlist locally, etc. Lets think about some improvements that can be made.

• REQ-2: As written, the system will automatically create the playlist whenever a user interacts with the control. Most of know that this isn't usually desired. Typically users want to have a secondary action like a Save or Cancel before actually creating such a playlist.
• REQ-3: Engineers have to ask themselves, "is 30 seconds a technically feasible implementation?". "If it were longer than 30 seconds what would the impact to the user be, would they care?". There may be more work here for the team to determine what is an acceptable time. In addition, as written we are only synchronizing the playlist when a user creates a playlist, why wouldn't we synchronize in the event of an edit or delete action?

Let's take some that into consideration and update our requirements.

Most are familiar with this thought but I want to state the obvious, these are not perfect or finished requirements. What I mean by that is until a team of the relevant stakeholders has reviewed the requirements, their rationale, their test plan, and they have agreed on each, the requirements are not done. I would like to cover the an effective requirement review process in another post. Until then, I hope there is a tidbit of helpful information here.