The root cause of over 70% IT project failures can be traced back to poorly written requirements. Learning how to write software requirements is essential if you want to deliver high-quality software on time and within budget.
In this article I'll help you do just that. Using my 15+ years of experience helping teams build great software, I’ll share 12 do's and don'ts for writing effective software requirements, so you can craft the perfect set of requirements and start delivering more successful software.
Software requirements are key to the success of any software project, providing a roadmap for the development process and serving as the basis for all decisions and actions taken by the project team:
Deliver your web app
in weeks not months
Now, let’s get into the 6 specific tips for writing a strong set of software requirements that communicate your project goals and user needs effectively. We’ll start with one of the most essential practices for anyone writing requirements: writing from the user’s perspective.
Software requirements should be written in plain language that reflects the user's perspective and terminology. They should be specific, yet understandable, with minimal technical or industry jargon. Focus on writing the requirements in such a way that all stakeholders can fully understand without needing to consult other documentation.
One of the best ways to do this is to write your requirements in user story format, where instead of the system being at the center of the requirement, the user is at the center. For example, we can turn this poorly-written requirement into something much better by writing it with the user at the center.
| BAD REQUIREMENT | GOOD REQUIREMENT |
|---|---|
| The shopping cart has a list of items and the total purchase price. | As a customer I want to be able to view a list of the items in my cart along with a total purchase price, so that I can decide quickly if I want to move forward with checkout. |
PRO TIP: Use graphics and pictorial tools as much as possible to help articulate the user’s viewpoint. For example, in the requirements document, you can highlight system features by including diagrams of use cases, sequence or activity charts, functional flow block diagrams, structure charts, allocation charts, data flow diagrams, object diagrams, storyboards, and entity-relationship diagrams.
Software requirement documents are not design documents. Therefore, they do not and should not define how the functional requirements must be executed from a design standpoint. Therefore, all of your functional requirements should be implementation-neutral. In other words, requirements should state what the system should do, but not how it should do it.
Doing so can ensure your requirements are adaptable and not dependent on a specific implementation tactic. In the end, this can help you save money as the development team will feel free to evaluate the most cost effective implementation options rather than be tied down to a specific path you assumed would be best. You can see this in practice with this requirement that went from a very specific implementation to a more general requirement, focusing on the end user.
| BAD REQUIREMENT | GOOD REQUIREMENT |
|---|---|
| The application must display the onboarding guide using a modal window with a width of 500px and a height of 300px. | The user should be able to view the onboarding guide regardless of what screen they are on. |
PRO TIP: While implementation details should be left up to the development team, there are certainly cases where you need to specify how the system should interact with another software system or what technical specs it will need to meet. These kinds of requirements should be defined in the non-functional requirements for the software application, rather than within the functional user stories.
It is important to involve stakeholders early and often during the software documentation process to ensure that the software will adequately meet the needs of everyone involved. Stakeholders should be:
When interfacing with so many different stakeholders, it can be helpful to improve your software requirement specifications with visuals like diagrams, schemes, and models that provide a visual representation of the system’s use cases, user journeys, screens and more. This can provide an easier way to understand and explain the features, flows, and scenarios that are part of the requirements.
For example, a flow chart like this could help stakeholders understand the complete picture of how the application is intended to function, so that they can better contribute to or analyze each functional requirement.
PRO TIP: It’s important to consider the role each stakeholder will play in the process. Some stakeholders, such as your IT team, may provide crucial technical input, while others, such as managers, may help adjust the overall scope of the project and provide final approval on the direction. Tailor the input you are requesting from each stakeholder to their role and personal strengths.
Drafting software requirements is a process best completed in phases. Once you have a set of high-level requirements, you are ready to begin the process of analyzing, refining, and decomposing your requirements using the following process:
To see this in action, we can break down the requirement on the left into three more specific requirements:
| BAD REQUIREMENT | GOOD REQUIREMENT |
|---|---|
| As a student I need to be able to complete lessons within my eLearning courses. | 1. As a student I need to be able to watch video lessons within my eLearning courses. 2. As a student I need to be able to read text-based lessons within my eLearning courses. 3. As a student I need to be able to progress through each lesson in order, without jumping ahead to future lessons within my eLearning courses. |
PRO TIP: Use operational scenarios to the extent possible to demonstrate, or bring to life, what the requirements are trying to capture. Operational scenarios portray the product, end-user, and other entities in the intended environment, and are a useful tool for discovering and refining requirements.
Prioritizing software requirements is key as it helps ensure that the most important features are developed and implemented first, maximizing the value of the software for the users. Successful prioritization requires a well-defined prioritization matrix, which should:
For example, a well defined prioritization matrix could look like:
| PRIORITY | DEFINITION |
| 1 | Highest priority, core functionality and/or must have basic customer success in MVP |
| 2 | Medium priority, ideally is included in the MVP, as it enables more advanced functionality |
| 3 | Lowest priority, would be nice to have, but not required for MVP |
Once a prioritization matrix has been defined, the team can work together to set priorities based on the end-goals of the software, the project’s initial budget and timeline.
PRO TIP: Communicating your prioritization matrix is nearly as important as creating it in the first place. All of the project’s stakeholders need to be made aware of how requirements will be prioritized and the proper project management process for requesting changes to priorities. It’s a best practice to define this early as part of a broader requirements management plan.
Modification is an inherent characteristic of the software development cycle. No matter how well documented the initial set of requirements is, project managers and software developers must cope with an ever-changing set of requirements throughout development.
Requirements can change for plenty of reasons such as unanticipated problems during software development, budget cuts, personnel changes, and changes to the project schedule.
Having a change management system and process in place is crucial. This is what the requirements change management process looks like in most software development projects:
PRO TIP: Supervising requirements is a continuous process and is conducted throughout a system’s life-cycle. At each technical review, the project lead should review the software requirements document with the purpose of ensuring that the requirements continue to meet the requests and expectations of its customers and stakeholders.
Now that we’ve discussed a few best practices for putting together a software requirements specification, let’s look at a few things you should avoid if you want to maximize the success of your project.
Ambiguous language and technical jargon can lead to misunderstandings and wasted time. Even if you think everyone on the project will know what you mean, it’s important to be specific and clear and not make any assumptions..
For example, this requirement would need to be re-written to provide specifics on what we mean by “easy to use” and “intuitive.”
| BAD REQUIREMENT | GOOD REQUIREMENT |
|---|---|
| The system should provide an intuitive user interface that is easy to use. | The user should always be able to access the Homepage in one-click. |
PRO TIP:
Leaving off acceptance criteria when writing software requirements can be detrimental to the development process. Without clear acceptance criteria, developers may not understand the exact requirements of the project, which can lead to them making incorrect assumptions about or interpretations of the requirements. It also means that there’s no one way to validate if the requirement has been satisfied.
| BAD REQUIREMENT | GOOD REQUIREMENT |
|---|---|
| The user must be able to search for employees by department. | The user must be able to search for employees by department. 1. The user must be able to select a department from a list of available departments. 2. The search must return a list of employees in the selected department. 3. The search results must include the employee's name, department, and title. 4. The search must be completed within 5 seconds. |
PRO TIP: Update your existing SRS template to require acceptance criteria for every requirement.
It is important to use a standardized format when creating software requirements specifications, as it helps ensure that all requirements are specified in a consistent and understandable manner that can be easily understood by all stakeholders and updated in the future.
To get started improving standardization, re-write requirements in a common format such as:
| BAD REQUIREMENTS | GOOD REQUIREMENTS |
|---|---|
| 1. The application must be able to track and display sales data in real-time. 2. Users must be able to access the application from any device with a web browser. 3. All pages must be secure and password protected. | Admins must be able to pull a real-time sales data report. Users must be able to access the application from any device with a web browser. Users should be required to enter a password before accessing any pages of the application. |
PRO TIP:
It is important to not make technical assumptions when writing the software requirements document. Do not simply assume that your development team will use certain technologies or understand the technical requirements of the system. Nonfunctional requirements should clearly list any technical requirements of the system, such as the use of certain technologies or the necessity of particular software interfaces.
For example, instead of writing a requirement in a way that assumes a relational database will be used, we can instead write it to focus on the functionality from the user’s perspective:
| BAD REQUIREMENT | GOOD REQUIREMENT |
|---|---|
| Real-time analytics of user activity data should be stored in the relational database. | Admins should have access to real-time analytics of user activity data. |
PRO TIP:
It is important to ensure that there are no conflicting requirements in your software requirements document. Having requirements that conflict can cause confusion and ambiguity when developing software, which can ultimately lead to expensive delays or even project failure.
Conflicts can happen inadvertently, especially during the requirements elicitation process for complex software solutions. It’s important to carefully review possible conflicts and revise them to provide clarity, such as in this example:
| BAD REQUIREMENT | GOOD REQUIREMENT |
|---|---|
| 1. Team leaders should have full access to reports. 2. Admins should be able to assign “read only” or “edit” permissions to each team leader individually. | 1. Team leaders should, by default, be given “edit” access to reports. 2. Admins should be able to change the reports permissions for individual team leaders to assign them either “edit” or “read only” access. |
PRO TIP:
Non-functional requirements are important part of software requirement specification document as they help define the quality of the desired system and the expectations of the stakeholders.
Many teams neglect non-functional requirements, assuming they are less critical than functional requirements that are defined as user stories. However, without them software solutions may be built that does not meet the core expectations of stakeholders from a security, quality, or reliability perspective
Non-functional requirements should address:
| Security | Will you be storing PII or other sensitive data? Does your company have any specific security standards that should be adhered to? |
| Capacity | What kind of data storage requirements do you have? Do you expect your needs to change over time? |
| Compatibility | What are the minimum hardware requirements? What are the technical limitations that should be considered? Are there any specific external interface requirements? |
| Reliability | Do users need 24/7 access? What are the acceptable down times for your system to still meet a user’s basic needs? |
| Scalability | What is the maximum load that should be able to be handled? Consider both data and user traffic. |
| Usability | Are there specific UX standards that should be followed? Consider also ADA accessibility. |
PRO TIP: Use concrete language to describe the desired behavior of the software. Avoid vague terms like "efficient" or "user-friendly" and instead focus on specific criteria that the software should meet, using as much detail as possible.
Writing effective software requirements is key to delivering reliable and successful software. By following the do's and don'ts outlined in this article, you can be sure to create a set of requirements that are concise, precise, and clear.
If you're looking for help drafting a technically-sound set of requirements, consider utilizing our software development consulting services. We can help you evaluate your business needs and turn them into a detailed set of software requirements that will set you up for a successful development process.
Or, leverage our end-to-end software product development services, where our team will help you plan, design and build a great software product without any headache. Don’t hesitate to contact us for a no-strings-attached consultation.
Author Błażej Kosmowski CTO