Software Requirements Specifications (SRS)
This article will list eight guidelines that will help you create a well-written SRS that is both complete and unambiguous
SRS are created to describe the functional and the non-functional requirements of what should be implemented in the system
1. Use-Cases
Use-case is a term that comes from the object-oriented world.
Use-case diagrams depict interactions between actors (users, systems,
entities) and functions of a system. A use-case diagram helps you get a
high-level view of the system. It is a great starting point before
detailed specification requirements are created.
Take a look at the following use-case diagram that describes a use-case and actor interactions for an ATM machine.
The actors of the system are:
1. User
2. ATM Machine
3. Bank
The functions (use-cases) of the system are:
1. Login
2. Get Balance Information
3. Withdraw Cash
4. Transfer Funds
5. Deposit Cash
Notice that use-cases start with a verb.
The use-case diagram above reveals the following facts about this system:
1. Identifies actors and functions of the system
2. Identifies interactions between actors and features of the system
3. Hints at the scope of the system
2. Use-Case Realization
Using use-case semantics for deriving functions of the system can
greatly benefit you when composing the software requirements
specifications (SRS). Use-cases are universally accepted in the software
development community and they promote structure and completeness of
the SRS.
Once a high-level use-case diagram is completed, a more detailed
description of each use-case can start. The exercise of creating a more
detailed use-case is also called a "Use-Case Realization." Each use-case
contains a sequence of events (steps) that describe its execution flow.
Furthermore, each use-case has a number of alternate paths, exceptions,
pre-conditions, and post-conditions.
A common structure of a use-case realization consists of the following sections:
1. Name: The name of the use-case
2. Description: A brief explanation of what this use-case is achieving
3. Actors: All participants of the use-case
4. Pre-Conditions: All major events and states of the system that must be present before the use-case can be executed
5. Post-Conditions: All major states that the system assumes after the use-case is executed
6. Successful Path: All steps that fully describe successful execution of the use-case
7. Paths: All steps that describe alternate execution of the use-case
(If there are multiple alternate paths or alternate paths are lengthy,
you might want to consider creating a separate use-case for it.)
8. Exceptions: All errors that occur during execution of successful and alternate paths
9. Rules: All business rules, computations, regulations, formulas, and constraints of the system
Try to create a simple use-case realization for a "Withdraw Cash" use-case:
1. Name: Withdraw Cash
2. Description: This use-case realizes cash withdrawal use case.
First, the client requests cash. If there is enough cash in the client's
account, the ATM disperses the specified amount and notifies the client
of the new account balance and dispersed amount
3. Actors: Client, ATM, Bank, System
4. Pre-Conditions: Client is logged in
5.
Post-Conditions:
a. Cash is dispersed
b. Client's account balance is updated
c. Client is notified of the transaction
6.
Successful Path:
a. The client requests cash withdrawal
b. The system establishes a connection with the Bank
c. The system retrieves client's available account types
d. The system displays available account types
e. The client chooses a desired account type
f. The client enters the amount to withdraw
g. The system retrieves the selected account balance from the Bank
h. The system validates available funds against account balance (see computation a in the Rules section below)
i. The system prompts for confirmation
j. The client confirms withdrawal amount
k. The system computes new balance (see computation b in the Rules section below)
l. The system disconnects from the Bank
m. The system disperses specified amount
n. The system prompts that cash is dispersed
o. The system notifies the client of his transaction
7.
Alternate Paths: Start from step h in the successful path. The selected account type does not have sufficient funds:
a. The system prompts the client that the withdrawal amount exceeds the account balance
b. The system displays available account types
8.
Exceptions:
a. No available account types: The system prompts that "No available account types exit"
b. Requested amount exceeds account balance: The system prompts that "The requested amount exceeds account balance"
9.
Rules:
a. Available funds computation: Withdrawal amount must be less than or equal to account balance
b. New balance computation: Deduct withdrawal amount from account balance
Look at another use-case realization for the "Login" functionality:
1. Name: Login
2. Description: This use-case realizes the login function of the
system. The client inserts a bank card into the ATM card slot and enters
his password. If the password is correct, the system logs the client
in.
3. Actors: Client, ATM, Bank, System, Bank Card
4. Pre-Conditions: None
5. Post-Conditions: Client is logged in
6. Successful Path:
1. The client inserts his bank card into the ATM card slot
2. The system validates the credit card
3. The system prompts for the client's password
4. The client enters the password
5. The client confirms password entry
6. The system validates the password
7. The system logs the client into the system
7. Alternate Paths: Start from Step 5 in the successful path
a. The system validates the password and the password is incorrect
b. The system increments invalid login count by 1
c. The system notifies the client that the password is incorrect
d. The system prompts for password
Exceptions:
. Bank card is disabled
a. Account is locked
b. Bank card is reported stolen
c. Password is incorrect
Rules: Client account gets locked out after three unsuccessful
login attempts.
In the above example, you have listed steps that actors perform to
realize a use-case. Now, you can use these use-case realizations to
start deriving more precise functional requirements.
3. Structure
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.
Create a hierarchy for your ATM system.
1. Business Requirements
1.1 Login
1.1.1 Validate Bank Card
1.1.1.1 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"
1.1.1.2 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"
1.1.1.3 Validate for Disabled Card
Validate that the card is not disabled
If card is disabled, prompt error message "Card has been disabled as of"
1.1.1.4 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
1.1.2.1 Validate that the password is not blank
If password is blank, prompt error message "Please provide password"
1.1.2.2 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
1.1.4.1 Increment Login Counter
For every consecutive Login attempt, increment logic counter by 1.
1.1.4.2 Reset Login Counter
Reset login counter to 0 after login is successful.
1.2 Get Balance Information
1.2.1 ...
1.2.X ...
1.3 Withdraw Cash
1.3.1 ...
1.3.X ...
1.4 Transfer Funds
1.4.1 ...
1.4.X ...
1.5 Deposit Cash
1.5.1 ...
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 1.1.1.1 (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.
5. Keep Technology and Design Out
Why keep technology out of business requirements? It took me a
while to agree and comply with this rule. As a technologist, I am
tempted to solve the problem, come up with a solution, and design the
system. It is important to understand that you, as an author of software
requirements specifications, should only concern yourself with WHAT the
system must do and not with HOW it will do it. In other words, you must
leave implementation decisions to those who will create the technical
design specifications. SRS is a document that should be technology free.
"The system" (as you call it) happens to be a piece of software that
runs on a computer. When composing the SRS, try thinking of "The system"
as an entity that has nothing to do with software.
The same goes for designing screens while creating SRS. Even if you
have a degree in GUI design and extensive knowledge of "client/system
experience," you must refrain from mixing technology (how to do it) with
requirements (what is needed).
Remember, SRS describes the functional and non-functional
requirements of a system. "A list of available account types" is a
requirement, whereas "a dropdown menu of available account types" is an
implementation of that requirement.
The following words should not be used in the SRS: Click, dropdown,
screen, and checkbox. Instead, use such terms as press, select, and
prompt.
6. Make the SRS as Complete as Possible
Incomplete software requirements specifications leave room for
ambiguity which leads to more questions later on. Incomplete means
"missing information." Sooner or later, somebody must list all
validation rules for the "Validate Bank Card" requirement. If SRS is
unambiguous, there are fewer questions, fewer assumptions, and therefore
less rework later on in the project's lifecycle. You can think of it
this way:
An application developer is like a truck driver. The truck driver
has to pick up and deliver freight based on a predefined schedule. If
the truck driver does not know the schedule, he will set his own
schedule and he will improvise.
Furthermore, a complete SRS allows application developers and the
quality assurance team to provide more specific estimates. Can anybody
give an accurate estimate on how long it will take to develop and
unit-test the "Validate Bank Card" functionality? Unless it is
decomposed into very specific requirements that can no longer be
decomposed, the estimation would be inaccurate. However, once you know
that "Validate Bank Card" consists of four specific unambiguous
requirements, you can provide a more accurate estimate.
There is another important point: The quality assurance team can
start creating test-cases as soon as SRS is complete. The benefit here
is two-fold:
1. The QA team can start creating test cases during requirements
gathering instead of after application development is complete. This can
be done because complete SRS tells you a full story.
2. This is a very useful exercise because it validates whether the
SRS is complete and unambiguous and if use-case realizations are correct
and make sense.
7. Define the Level of Detail
You have already learned that the SRS must be complete and without
any ambiguous terms. But what might look ambiguous to one community of
readers might not be ambiguous at all to another community. Before you
start composing the SRS, get an idea of who will develop your system.
Will the development be done by an in-house IT or outsourced to a
vendor? If it is done by an in-house IT, the staff is probably familiar
with terms used in the SRS (proprietary systems, business terms,
abbreviations). If the SRS is to be handed off to a vendor, the content
should be as detailed as possible.
Also, keep in mind that your audience consists of stakeholders,
developers, QA, and product managers. You must find the common language
among all of these groups.
Let me give you a trivial example:
Company XYZ has implemented a single sign-on solution called
"ComSec." You are working on the SRS that describes a future system
that will utilize "ComSec" for all its user authorization and
entitlement. Now, you might choose to describe user authentication and
entitlement use-case like this: "The system shall use "ComSec" as the
means to user authentication and entitlement." Is this enough
information to implement this requirement? For somebody who understands
"ComSec" it is, but for an outsider it most definitely is not.
8. Get Formal Training
Composition of well-written Business Requirements is done via a
methodology. This methodology has been studied by many people who have
many years of professional experience creating software specification
requirements. It is essential that you consult with their expertise
either by obtaining formal training or by reading publication on the
subject.
SRS documentation is a foundation for all future deliverables�test
cases, design specs, and source code. SRS is also an input to such
project activities as scope planning and definition, cost estimating and
budgeting, human resources planning, and so on. How long does it take
to modify or add a business requirement before subsequent phases of the
project are initiated? No time at all. Now, imagine adding a new
requirement when the project is well underway. Test cases will have to
be modified, design specs revised, code re-written, user manuals and
training materials updated. Thus, complete, well-written, and
unambiguous SRS is a key to a successful project that is on time, on
budget, and within the intended scope.
If your organization has been experiencing problems developing
application that are on time, on budget, and according to client and
stakeholder expectations, it might be wise to introduce some formal
training. If formal training cannot be achieved, there are numerous
technical books on the market to help you achieve your goals
Conclusion
I hope this article will help you create better Software
Specification Requirements. I say this often when I write articles of
this sort, but I have to say it again: Knowing the rules is not enough
to get you where you want to be. Following these rules is what gets you
there.
Another important point is that the above rules are only guidelines
and they often need to be broken when there is not enough time or not
enough resources to complete a task.
