The collection, the analysis and the documentation of requirements are essential all along the life cycle of a software project. Requirements describe the stakeholders’s vision of the system, the behavior of the latter, the interactions of the users with it and the environment in which it will be used.
The writing process of requirements implies many stakeholders, who may differ depending on the industry.
A well written document is crucial, because it is the ground on which the needs will be defined, as well as the calculation of the project budget. It will also enable to monitor the project.
This article aims to provide 8 best practices regarding software requirements. Those tips are very operational and will facilitate the life cycle of the project.
Let’s start with a reminder of the definition of software requirements according to IEEE & CMMI:
- A condition or capability needed by a user to solve a problem or achieve an objective,
- A condition or capability that must be met or possessed by a system or system component to satisfy a contract, standard, specification, or other formally imposed document,
- A documented representation of a condition or capability as in 1 or 2.
Who is in charge of writing the requirements? All the stakeholders, such as:
- The client,
- The person in charge of the requirement specifications,
- The marketers,
- the project manager,
- The technical writer,
- The designer,
- The analyst,
- The developers,
- The boss.
It is among the best practices to involve ALL the stakeholders in the review and validation process (analysts, technical designers, developers, testers, integrators, etc.) of the requirements.
The main requirement sources are:
for a project:
- The requirement specifications of the client,
- The study of the project,
- The delivery terms and conditions,
- Each agreement implying the client,
for a maintenance contract:
- The evolution demands,
- The judgment and perception of the client,
- The evolution of marketing and sales strategies.
The less documents we have, the better the situation we find ourselves in. It is strongly advised to only have one requirement document. Tools such as Jira offer this feature in only one place, and it can be shared with the stakeholders, all along the life cycle of the project, and even of the product.
One of the biggest difficulties lies in the fact that clients (users) tend to get confused between needs (business requirements) and solutions (product requirements).
Instances of product requirements:
- “the system must use passwords”,
- “the system must have a graphic interface”,
- “the system must automatically disconnect after two minutes of inactivity”.
The main writing defaults are:
- Noise: useless or irrelevant piece of information,
- Remorse: kind of noise that changes the text a posteriori,
- Silence: lack of information, a notion that has not been explained,
- Overspecification: to many details about the solution (drifts toward the conception),
- Inconsistency: internal contradiction, conflicting requirements,
- Ambiguity: vague terms, with several interpretations,
- Unverifiable requirements: vain wishes,
- Redundancy, failure to respect the standards, missing requirements, etc.
Documents of this type are too often not reliable and must be reworked by refining the requirements that are:
- Implicit (“it was so obvious”),
- Failing to encompass all the stakeholders,
- Too complete,
The main problems encountered in requirement specifications are the following:
- Describes the solutions, not the need,
- Ambiguity of requests,
- Too much implicit information,
- Fail to describe the business.
Even more when the requirement specifications are written by IT engineers. They tend to focus more on the technical solution than on the initial needs.
When the requirement specifications are written by someone else, they can end up being unrealistic.
A requirement must be complete and precise, consistent, measurable, verifiable, prioritized and classified.
Complete and precise
Requirements must be neither ambiguous nor poorly defined, but rather complete and precise. They must translate the user’s needs in order to address his/her business needs, and still be understandable by all the stakeholders.
Example: “The application must be integrated in the payment systems”.
The requirements will be written as follows: “The application will use PayPal and Direct Pay as payment systems”.
Be careful with punctuation:
- “The software calculates the speed of the missile and its trajectory, in less than five seconds”
has a different meaning from:
- “The software calculates the speed of the missile, and its trajectory in less than five seconds”.
Use precise and explicit words:
“On the outside, le records must appear as…”, but what does “on the outside” mean?
A same word may be understood differently by different people.
- Provide a glossary for the industry related terms.
- Avoid the “etc.”.
- If some uncertainty remains, use acronyms such as TBD (To Be Defined).
Requirements must be concise:
The requirement document addresses the needs of several stakeholders experts in different fields. It must then be concise and must make sense for all stakeholders.
Write short sentences:
- useless modal verbs: “can”, “should”, “could”.
- Pick active forms over passive:
- “If an error is detected, the software must be stopped”; who detects, who stops?
- Avoid double negations.
Write simple requirements:
Write simple sentences, present tense, addressing only one aspect.
Example: “The library initialized by data concerning books, is fed with data regarding the users”,
2 needs, 2 requirements:
- “The library is initialized by data concerning books”,
- “The library is fed with data regarding the users”.
Example: “The software calculates the trajectory of the missile in less than 5 seconds”
2 classes: functional and performance (2 requirements):
- “The software calculates the trajectory of the missile in less than 5 seconds” (functional) and
- “The calculation of the trajectory of the missile is done in less than 5 seconds” (non functional: performance).
The User Story
In order to facilitate the writing, it is advised to use a user story approach.
User Stories are like “stories”, expressed as sentences:
with: an actor,
doing an action,
to achieve a defined objective.
Example: the player activates his/her character arm for it to shoot.
To get used to write user stories, you should adopt the following writing format: “As a …, I …, in order to …”.
Example: “As a user, I can activate the arm of my character in order to make him shoot”.
That writing format is useful because it enables to understand the point of view of the user. It then enables to get closer to the granularity level offering a measurable exigence.
Requirements can be neither redundant nor contradictory. The user must make a choice in the case of a conflict. Requirements must be compatible so that all the features are clear for all the stakeholders.
Two requirements cannot contradict one another. “The A input only appears when the B input appears”.
When ten pages later, we can read: “The B input must begin 15 seconds after the appearance of the A input”.
Example: in two different places of the requirement specifications:
“The max withdrawal is of 1.800€” and “The amount of withdrawals is between 100€ and 1.800€”.
Requirements must be written with a basic level of features from the point of view of the user. The high-level requirements must be broken down by granularity levels, to clarify the requirements. All the requirements must be presented as individual and distinct entities.
The correct level of granularity depends on the unit which was defined to measure the size (or weight) of the adopted requirements. It may be a unit of work system, Function Points, or whatever software sizing system.
Example: “The application must create new work orders and update the existing work orders”.
The requirement must be rewritten as follows: “The application must create new work orders, with the capacity of altering and updating the existing work orders”.
Requirements and Function Point sizing
If you want your requirements to be easily measurable in Function Points, choose the “elementary process” granularity level defined by IFPUG:
Elementary process: the smallest significant activity for the user.
To identify each elementary process, you must complete the following:
- a) compose and/or decompose the user functional needs at the smallest activity level, that addresses the following points:
- is significant for the user,
- is an entire transaction,
- is autonomous,
- keeps the application in a coherent state.
Example 1: a functional requirement can indicate that a function must be provided to manage employee data. That requirement is divided into smaller units of work, such as “add an employee”, “change employee”, “delete employee” or “see employee”.
Example 2: the individual requirements may indicate it is necessary to add different types of data about employees (such as the address, the salary and related data), but the smallest significant activity unit for the user is “add an employee”.
Be careful of “fractalization”.
We often come across this phenomenon in descending decomposition, which consists in adding details progressively. For each new level of decomposition, the global size inflates.
Requirements must be verifiable: requirements cannot include abstract terms such as “good”, “excellent” or “efficient”. More quantitative and measurable terms must be used.
Requirements must be verifiable under expertise and environment constraints. Non-functional requirements must have a quantitative value for them to be verifiable.
To make a requirement verifiable, you have to imagine how it will be verified, its validation criteria:
Example 1: “The system must be performant”.
That requirement must be written as follow: “The page must be loaded in 5 seconds”.
Example 2: “The application will show good performance”.
The requirement will be written as follow: “The application will load the page in 5 seconds”.
Example 3: “The human-machine interface is user friendly”, to be transformed in:
- The data access features are displayed in a drop down list.
- A support menu corresponds to each input element.
Check the non-functional requirements: a few tips
|Requirement types||How to verify them|
|Appearance||Compliance with standards – mentioning who will test it and how|
|Usability/user friendly||Training time needed|
|Performance||Maximum time needed to complete an action|
|Operational||Time and simplicity of use in the environment|
|Maintenance||Maximum time to make changes Effort quantification to carry the system|
|Security||Who can have access to the system|
|Legal||Validation by a jurist|
|Political||Person or entity to do the validation|
The client can easily prioritize his/her business needs. Consequently, taking into account the significance of the requirement and documenting it is part of the best practices. You will then be able to prioritize the requirements. The requirements that are important to the client cannot be omitted. This will help you to determine which requirements you will keep if you have to fit in a budget or deliver quickly.
Prioritizing each requirement is one of the best practices that facilitate the arbitration of the perimeter of the product if necessary.
The functional requirement document cannot include implementation nor conception requirements. The document can only include answers to the functional needs of the stakeholders.
One of the best practices consists in marking each requirement according to its type, knowing that deliverables or measure and specific test systems will correspond to each type of requirement
As a reminder, regarding software projects, there are several types of requirements:
- functional requirements,
- non functional requirements.
- Constraints: “requirement, obligation, inconvenience, related to the use or to a necessity”.
In IT, constraints are often either related to what does already exist (other tools) or are related to external stimuli (law, standards, etc.).