Software Requirements Specifications: The Right Way
Choosing the right structure for your SRS is extremely important. In his book Software Requirements, 2nd edition, Karl E. Wiegers suggests that requirements must be written in a hierarchy. Each level of the hierarchy should drill down to a more specific set of requirements. The hierarchical approach provides several benefits:
- Each requirement is traceable to its parent. You can always trace a child to a parent and vise versa.
- Each requirement can be verified for completeness because because, based on the children, you can verify whether the parent is complete.
The very top parent of your requirements hierarchy is, of course, "Business Requirements." The children of the "Business Requirements" parent are all the high-level use-cases that you show in the use-case diagram. The next level consists of less general requirements, and so on, until requirements can no longer be broken up into more specific requirements. The lowest level of the hierarchy must have requirements that cannot be broken down further.
1. Business Requirements
1.1.1 Validate Bank Card
22.214.171.124 Validate for Card Expiration Date
Validate that the card's expiration date is
later than today's date
If card is expired, prompt error message "Card is expired"
126.96.36.199 Validate for Stolen or Lost Card
Validate that the card is not reported lost or stolen
If card is lost, prompt error message "Card has been reported lost"
If card is stolen, prompt error message "Card has been reported stolen"
188.8.131.52 Validate for Disabled Card
Validate that the card is not disabled
If card is disabled, prompt error message "Card has been disabled as of <expiration date>"
184.108.40.206 Validate for Locked Account
Validate that the account is not locked
If account is locked, prompt error message "Account is locked"
1.1.2 Validate Password
220.127.116.11 Validate that the password is not blank
If password is blank, prompt error message "Please provide password"
18.104.22.168 Validate that the password entered matches the password on file
If password does not match, prompt error message "Password is Incorrect"
1.1.3 Lock Account
If number of consecutive unsuccessful logins exceeds three attempts, lock account
1.1.4 Maintain Consecutive Unsuccessful Login Counter
22.214.171.124 Increment Login Counter
For every consecutive Login attempt, increment logic counter by 1.
126.96.36.199 Reset Login Counter
Reset login counter to 0 after login is successful.
1.2 Get Balance Information
1.3 Withdraw Cash
1.4 Transfer Funds
1.5 Deposit Cash
In the example above, you have fully (at least in the context of this exercise) decomposed the "Login" use-case. If you examine functional requirement 188.8.131.52 (Card Expiration Date), you will find that it cannot be further decomposed; this means that you can no longer break it up into a more specific set of requirements.
Now, look at section 1.1.1 (Validate Bank Card). This section, on its own (without its children), is obviously ambiguous and must be broken down into a more specific set of functional requirements.
The hierarchical structure does not merely help you organize the document better, it also aids in figuring out whether the functional requirements are complete. It is easier to verify whether the "Validate Bank Card" functional requirement is complete if you can review its children instead of looking throughout the whole document for various validation rules.
4. Use Correct Language
You must always use the active voice when writing business requirements. Passive voice adds ambiguity to the document. Here are several examples:
Passive voice: When password and user name are entered, they are validated.
Problems: Who checks for correctness—the user or application? Who enters the password and user name?
Active voice: The system validates the user name and password that the user provided.
Passive voice: Notification is sent.
Problems: Who sends the notification—teller, system?
Active voice: The system sends notification to the client.
The SRS must have precise and strong language. You must use words such as must and shall and stay away from such vague words as should, would, user-friendly, effective, usually, slow, fast, and almost always.
Here are several examples:
Incorrect statement: The system usually should respond fast.
Problems: What is the definition of fast—2 seconds or 10 seconds? What does usually mean—50% of the time, or 90% of the time?
Correct statement: The system must respond to user requests in two seconds or under for 90% of requests.
Incorrect statement: Because the user almost always requests a hard copy report, the system should provide this capability on demand.
Problems: What does almost always mean?
Correct statement: The system must provide a hard copy report on demand.
Page 2 of 3