There is a discernable difference between novice and veteran requirement writers. The process is more art than science, but it still has some best practices that can be of help to anyone. Here are some points to consider that can help you make your next requirements document the best one you have written.
Outline the Requirements
In my experience, this is the most natural step. Start with a high-level overview of needs for the project. This helps set the stage for greater detail while providing a core design. It is important to have this basic design as it provides a reference point as the details are refined that can help avoid drift. Once this outline is created it can, and should, be regularly referenced during the definition of detailed requirements to ensure the details link back to core features.
The highest level outline of requirements is the vision for the project. The outline is the general view of what is to be created and drift from the vision is highly discouraged. It does not mean the vision cannot be altered or refined. However, a project is a plan for moving from A to B. The B is the vision. Therefore, changing B as the focus can create situations where you “take the scenic route” or even become hopelessly lost.
Ask “Now What?”
Once the outline comes together, it is time to go to the next level. This point is where most requirements fall apart. There are a set of questions that a well-defined requirement will answer. Let’s look at each one and what to consider in answering it.
How do I get to this point?
This question looks at how a requirement is executed. It includes considering who can access a feature and whether it has limits for different users or times. For example, an ATM has a requirement to dispense money. To receive cash, someone must be authenticated to the system (card and PIN). An authenticated user has made a request for withdrawal. The account has been selected, and it has a balance greater than the sum to dispense. Keep this example in mind as we look at the other questions.
What data should I have once I get to this requirement?
This question addresses the state or environment we can expect while fulfilling a need. It potentially includes defining how the data is gathered in the first place. Thus, we might find some more requirements to be determined while answering this question. In the above ATM example, we should have an account number, an authenticated flag and an amount to withdraw. Thus, we should have requirements defined that address how an account number is gathered, how to mark a user as authenticated, and how to tell the system what to withdraw.
What is the expectation when this requirement is fulfilled?
At this point, we define what success means for the requirement. If we can not determine success or failure of a requirement, then it is either not needed or ill-defined. For example, an ATM withdrawal results in cash dispensed and an account debited. There may be new expectations as well, but they should all be defined as part of answering this question.
Where do I go from this requirement?
The first question we asked is the entry to this requirement. This question is the exit. Once a requirement is fulfilled, we need to examine the options for proceeding. Often the answer to this issue is a list of “locations” based on success or failure. In the ATM example, we will show a success message, an error screen, or might go back to the main menu. This step is where we might turn up some other entry requirements to define. For example, is there a “quick cash” option that skips going back to the main menu and instead logs the user out after dispensing cash? Alternately, is there an optional “print receipt” step to consider?
What happens if an error occurs?
This is the question most often missed in my experience. Our vision is all about the success of the system, but errors occur, and those must be defined as well. In the ATM example, a user might not have a high enough balance to their account. The ATM might not have enough cash on hand, or the dispenser automation might be broken. The list of potential errors can get lengthy, but they need to be examined. This long list can be simplified into an “exception bucket” that covers errors we can’t think of, but the more we tightly define the errors and corrections the more reliable the result will be.
Do I need to communicate success or failure of this requirement?
I see this question skipped more often than I expect. Once a requirement can be considered a success or failure, does a notification need to occur? This may be a report, a log entry, or any other communication method. We might even want to provide multiple responses. In the ATM example, the notification is likely a printed receipt (report), a beep or sound to note the process is complete, and a message on the screen. Success is the most likely result to be communicated; it is the error communication that we often forget to define. Do we ping a maintenance service if the cash on hand is insufficient? Do we notify authorities if the authentication is a blatant fraud attempt? These sort of error messages should be defined and are as important (maybe more so) as the communication of success.
Defining requirements is an art form of sorts, but following some simple guidelines can make anyone more effective. If your requirements have not considered and answered these questions then doing so can improve the likelihood of a successful project.
