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.
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:
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.
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:
All of this is in addition to the requirements themselves, which fall into two main categories: functional and non-functional.
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.
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.
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:
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.