The software requirements document is the single most important input to any custom software project. It is also the document that most business leaders feel least equipped to write. As a result, technical teams may define requirements without fully understanding the business context. Alternatively, business teams may document them in a format that developers cannot use reliably.
Neither approach produces good outcomes. This article explains what a software requirements document needs to contain, what format works for business leaders writing their own requirements, and what the most common failure modes are.
What a Software Requirements Document Is For
A software requirements document does two things. It defines what the software needs to do in enough detail that a developer can build it and a tester can verify it. And it creates a shared understanding between the organization commissioning the software and the team building it about what success looks like.
A requirements document does not explain how developers should build the software. Instead, it describes what the software needs to do. Therefore, the organization makes the “what” decisions, while the development team makes the “how” decisions. If these roles become confused, the requirements may limit the team’s ability to make sound technical decisions.
What a Software Requirements Document Needs to Contain
Business Context and Problem Statement
Describe the business problem the software will solve and the context in which people will use it. Then, identify everyone the problem affects. What does the problem cost? What would a successful solution enable that is not currently possible? This context helps the development team understand why the requirements are what they are, which is essential for making good decisions when the requirements are incomplete or ambiguous.
User Stories or Use Cases
A description of who will use the system and what they need to accomplish with it. User stories in the format “as a [type of user], I need to [accomplish something], so that [outcome]” are a practical way for business leaders to document requirements. Each user story describes one specific thing the system needs to enable. The collection of user stories for all user types defines the scope of the system.
Functional Requirements
For each user story, the specific functional requirements that enable it.First, define the data the system must capture. Next, identify the calculations or transformations it must perform. Then, specify the outputs it must produce. Finally, document the rules that govern the process. Functional requirements should be specific enough that a developer can build to them and a tester can verify them with a yes or no answer.
Non-Functional Requirements
Non-functional requirements define how the system needs to perform rather than what it needs to do. Performance requirements: how many users need to use the system simultaneously? How quickly does it need to respond? First, define the authentication the system requires and which users can access specific data. Next, identify the regulatory standards the system must meet. Finally, specify the required level of uptime.
Integration Requirements
A list of every system the new software needs to exchange data with and a description of what data needs to flow in each direction. This is often the area where requirements documents are most incomplete, and integration complexity is consistently one of the most underestimated elements of custom software projects.
The Most Common Requirements Document Failures
Requirements That Are Too Vague to Build To
“The system should be easy to use.” “Reports should be fast.” “The interface should be clean.” These are aspirations, not requirements. A requirement needs to be specific enough that it is possible to determine whether the delivered software meets it. “A user with no prior training should be able to complete the standard inspection form in under ten minutes on a tablet” is a requirement.
Requirements That Specify the Solution
“The system should use a drop-down menu for selecting the category.” “The report should be in Excel format.” The development team should usually determine the technical implementation unless a specific business requirement limits its options. Specifying the solution in the requirements document limits the development team’s ability to propose better approaches.
Missing Edge Cases
Requirements documents frequently describe the happy path, the typical case where everything goes as expected, without describing what should happen when things go wrong. Teams must determine how the system will respond when a required integration is unavailable. They must also define what happens when a user submits an incomplete form or a calculation produces an unexpected result. Edge cases produce the most expensive surprises during development.
Frequently Asked Questions
The people who understand the business problem and the users who will use the system should own the requirements content. The development team or a business analyst should facilitate the process and help translate business requirements into the specific format required for development. Neither group alone produces requirements as good as the two working together.
As long as required to describe the system completely at the right level of detail. A focused system with limited scope may require ten to twenty pages. A complex enterprise platform may require fifty to one hundred pages or more. Length is not the measure of quality. Specificity and completeness are.
Functional requirements describe what the system does. They define the functions it performs, the data it processes, and the outputs it produces. In contrast, non-functional requirements describe how the system performs. They cover speed, security, availability, scalability, and compliance. Together, both types create a complete specification.
Templates are useful starting points. They ensure that common sections are not omitted and provide a format that development teams are familiar with. The content of the requirements still needs to be specific to the system being built. A template filled with generic content is not a requirements document.
The development team builds to what is specified and makes assumptions about what is not. Those assumptions may be correct or incorrect. When they are incorrect, rework is required. The cost of rework is typically three to five times the cost of getting the requirement right in the requirements document. Completeness is worth the investment.
