An architect wouldn’t design a custom house for you without knowing something about your family, lifestyle, hobbies, and tastes. These inputs, and more, inform the requirements for the house: how many bedrooms, how many floors, what type of kitchen, and so on. From these requirements, the architect can design the size and arrangement of the rooms and the style of the exterior.
The approach is much the same with software design. Before the developers can design databases and user interfaces, they want to know the requirements—that is, what the software needs to do. The requirements are derived from knowledge of a number of factors. The most important question is, what is the problem that needs to be solved?
In this article, we discuss how to take a pile of vague ideas and turn it into a well-structured, complete requirements document.
What Is a Requirements Document?
A requirements document specifies the functionality of a software product. It could cover the entire software product, a specific module or set of modules, or new functionality to be added to an existing product.
Regardless of its scope, the important thing about a requirements document is it’s limited to describing what the software should do, not how the software should do it. The “how” part is covered by software design documentation produced by developers or user interface designers.
The requirements document has two primary audiences:
- Developers – Use the document for guidance in making design decisions
- Testers – Use the document to design test cases
In many development teams, the requirements document is written by a “business analyst.” This person’s job is to understand the business processes involved and problems to be solved, as well as translate the customer/endusers’ ideas into something developers and testers can work with.
Parts of a Requirements Document
A complete understanding of software requirements involves knowledge of the environment in which it will be used. For this reason, a good requirements document covers the following topics:
- Constraints – External factors that might inform the software design. For example, does the customer’s IT team support Windows servers/Windows 10 on the desktop?
- Current- and future-state business processes – How the users perform their tasks now, and how they expect it to change with the aid of the software
- User environment – Where the software will be used: Office, warehouse, laboratory, classroom, factory floor. Will it be used on desktop PCs, laptops, tablets, mobile devices, or some combination? Will users wear gloves or other protective equipment? Will the environment be noisy, dirty, or low-light?
- User types – Different roles of the people who will be using the software
All of this is in addition to the requirements themselves, which fall into two main categories: functional and non-functional.
- Functional requirements describe the actual features and functionality of the software. These are written in a non-technical language from the user’s point of view and are directly testable.
- Non-functional requirements cover areas such as required interfaces with specific hardware, other software, and existing databases; performance requirements; and supportability and maintainability. These requirements often are not directly testable and must be verified by indirect means.
Writing Good Requirements
The traditional format for writing a functional requirement looks something like this:
The system shall enable a registered user to submit contact information, including name, email address, and mobile phone number,
for purposes of subscribing to the newsletter.
A more modern approach re-casts the requirement in terms of a user story:
As a registered user, I want to be able to provide my name, email address, and mobile phone number so I can subscribe to the newsletter.
Notice that in both cases, the requirement is clear, complete, and unambiguous, without dictating the type of data entry controls to use or their arrangements on the user interface. The developer or UI designer can take the requirement and design an appropriate interface from it.
Although it’s not specified in the requirement, the designer should know from usability best practices the fields should be implemented with data validation (for example, to ensure email addresses are in the correct format).
Contrast these with the following poor examples:
The system shall enable a user to sign up for the newsletter.
This doesn’t provide enough information. What is specifically needed? Is an email address sufficient? What type of user? Can anyone sign up for the newsletter, or do they have to be “registered users?”
The system shall provide fields for name, email address, and mobile phone; each field shall be 128 pixels wide and 22 pixels tall,
with a light yellow background.
This is far too prescriptive and doesn’t describe the purpose of the fields or reveal who will be using them.
Getting the ‘Right’ Requirements
It’s one thing to write the requirements appropriately. Far trickier is getting the “right” requirements to document in the first place. If you simply take everything the customer and users say at face value and try to create requirements out of it, the result may be a convoluted, confusing mess. Too often, customers don’t really know what they want or need, much less how to articulate it. You should ask lots of pointed questions to tease the actual requirements out of them.
Successful requirements elicitation takes a willingness to ask uncomfortable questions. You need some domain knowledge of the business process and a fair amount of intuition. Much of the discussion should be about the process and the problem to be solved rather than specific software requirements. Often, you can avoid time spent on unnecessary software requirements.
For example, if the users insist the software should be able to print all sales order confirmations automatically, it’s a fair question to ask, “Why?”
Is there perhaps another way that wouldn’t kill as many trees or take up as much physical storage space? If there’s a compelling reason to print—a regulatory or legal requirement, for example—so be it. But when the answer is, “Because we’ve always printed them,” it’s time to explore alternatives. There’s no point in automating a process that shouldn’t be done in the first place.
Most customers want to spend more time on solutions, but this should be avoided now. At this phase, all that’s needed is an understanding of what they need, not how it should look.
Practice Makes for Better (If Not Perfect) Requirements Documents
Writing a good requirements document is tricky and it takes a bit of practice. You will need feedback from various stakeholders and probably several drafts before a requirements document can be considered ready for use.
Get feedback from:
- Customers and users – Ensure the requirements are complete and correct
- Developers – Ensure the requirements are understandable and unambiguous
- Testers – Ensure test cases can be written from the requirements
If you find the process too daunting or just don’t have the knack for it, consider engaging a professional business analyst. Getting the requirements document right is vital to the success of any software project, and too important to be left to chance.
