How to Write Software Requirements - 12 Do's and Don'ts

17 min read
How to Write Software Requirements - 12 Do's and Don'ts

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.

Why are software requirements important?

Software requirements serve as the foundation for software design and development. A well-written set of requirements will clearly define what a software system must do in order to satisfy customer or user needs. Once written, software requirements serve as a way for each stakeholder to do their job effectively and stay in alignment with the other members of the project team.

PRO TIP: A well documented set of software requirements will:

  • Provide a shared understanding of the requirements of the system.
  • Ensure the development team builds software that meets customer and user expectations.
  • Provide a basis for testing the software to ensure it works as expected.
  • Ensure compliance with any legal or regulatory requirements.

What are the characteristics of good software requirements?

All software requirements, should be:

  • Concise - expressed in clear and brief language.
  • Precise - specific, defined, and unambiguous.
  • Clear - free from ambiguity and jargon.
  • Complete -include all necessary details for successful implementation.
  • Not contradictory - must not contradict each other or previously established requirements.
  • Testable - easily testable and verifiable.
  • Prioritized - organized in order of importance.

How to write software requirements - DO’s

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.

Write from the user’s viewpoint and in the user’s language

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 REQUIREMENTGOOD 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.

Write implementation-neutral requirements

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 REQUIREMENTGOOD 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.

Involve stakeholders early and often

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:

  • Consulted at the beginning of the requirement process for their input on the project scope, intended audience, and overall project objectives.
  • Asked to provide input on a draft of the requirements before development begins.
  • Notified of changes to the requirements or product scope during the software development process.

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.

Analyze, refine and decompose requirements

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:

  • Evaluate each high-level requirement for its feasibility, reliability within program limitations, and its ability to be verified. If the requirement is impossible to achieve within cost and schedule limits, it must be recognized as an issue and resolved by adjusting the budget, relaxing the schedule, and changing or eliminating the requirement.
  • Practice functional or object-oriented analysis to define a functional architecture that can be used as a basis for allocating requirements.
  • Analyze your new set of requirements against the following criteria:
    • Completeness: Are all higher-level requirements allocated?
    • Consistency: Is the content, format, and notation from the requirement to requirement, and specification to specification similar?
    • Feasibility: Can the requirement be met?
    • Balance: What are the trade-offs between requirements?
    • Verifiability/testability: Can the requirement be objectively verified?
    • Human factors: Is the design consistent with sound human factors principles?
  • Complete the definition of derived software requirements and examine them for consistency with system requirements, feasibility, and the effects of various implementation strategies. Monitor derived requirements size volatility since derived requirements are often a significant source of software size growth.

To see this in action, we can break down the requirement on the left into three more specific requirements:

BAD REQUIREMENTGOOD 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.

Specify the priority of 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:

  • Identify who has the power to request or decide on requirement priorities.
  • Establish a standard set of priorities such as: “must have”, “should have” and “nice to have” or priorities 1-10.
  • Define the criteria for each priority label. In other words, what justifies a requirement being “1” vs “10” or “nice to have” vs “must have”?

For example, a well defined prioritization matrix could look like:

PRIORITYDEFINITION
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.

Track changes systematically

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.

How to write software requirements - DON’Ts

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.

Use ambiguous language and technical jargon

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 REQUIREMENTGOOD 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:

  • Spell out any acronyms and abbreviations.
  • Explain any internal institutional knowledge that may not be known to 3rd party groups.
  • If technical jargon is absolutely necessary, define it in an appendix.
  • Have someone from outside the core team review the requirements to ensure they are clear.

Leave off acceptance criteria

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 REQUIREMENTGOOD 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.

  • Review and update acceptance criteria regularly throughout the development process.
  • Involve the developers in the process of writing acceptance criteria to ensure the requirements are feasible and clear.

Neglect using a standardized format

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 now and in the future.

To get started improving standardization, re-write requirements in a common format such as:

BAD REQUIREMENTSGOOD 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:

  • Establish an accepted software requirements specification format and ensure that all stakeholders are on the same page about how to use it.
  • Use templates or checklists to ensure that all documents adhere to the accepted format .
  • Establish a process for approving and signing off on software requirements documents.
  • Provide training and/or reference materials to ensure that all stakeholders understand the accepted format for the software requirements specification and any related guidelines or standards.

Make technical assumptions

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 REQUIREMENTGOOD 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:

  • Write down any assumptions you are making and then work to include those assumptions as non-functional requirements within your software requirement specification document.
  • Break down high-level requirements into lower-level requirements. Going through this process can help to identify any assumptions you are making.

Add conflicting requirements

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 when defining requirements for complex features. It’s important to carefully review possible conflicts and revise them to provide clarity, such as in this example:

BAD REQUIREMENTGOOD 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:

  • Identify any potential conflicts before the requirements are handed off to the development team.
  • Assign one owner who will add requirements to the official list rather than having it open to all stakeholders to add requirements directly.
  • Document all changes to requirements and a process for vetting changes before they become final.

Forget about non-functional requirements

Nonfunctional requirements are essential in a software requirement specification document as they help define the quality of the desired system and the expectations of the stakeholders. Many teams neglect nonfunctional requirements, assuming they are less critical than functional requirements that are defined as user stories.

However, without non-functional requirements, a system may be built that does not meet the core expectations of stakeholders from a security, quality, or reliability perspective. Nonfunctional requirements should address:

SecurityWill you be storing PII or other sensitive data? Does your company have any specific security standards that should be adhered to?
CapacityWhat kind of data storage requirements do you have? Do you expect your needs to change over time?
CompatibilityWhat are the minimum hardware requirements? What are the technical limitations that should be considered? Are there any specific external interface requirements?
ReliabilityDo users need 24/7 access? What are the acceptable down times for your system to still meet a user’s basic needs?
ScalabilityWhat is the maximum load that should be able to be handled? Consider both data and user traffic.
UsabilityAre 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.

Conclusion

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.