http://www.developer.com/

Back to article

Software Requirements Specifications: The Right Way


June 4, 2007

Before you start getting into the how, let me talk about the why. Why do you need software requirements specifications (SRS)?

SRS are created to describe the functional and the non-functional requirements of what should be implemented in the system.The audience of software requirements specifications does not only consist of application developers, but of all the stakeholders—testers, project managers, users of the future system, and sponsors. SRS is a source of such deliverables as design specs, test cases, as well as budget and resource estimations. This is why it is so important that software requirements specifications are created in a way that is both complete and unambiguous. Once the SRS are published, any future changes to the document will create a ripple effect: The change created in the SRS will have to be reflected in all the documents that have been produced based on the SRS. This article will list eight guidelines that will help you create a well-written SRS that is both complete and unambiguous.

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.



Click here for a larger image.

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:
    1. Cash is dispersed
    2. Client's account balance is updated
    3. Client is notified of the transaction
  6. Successful Path:
    1. The client requests cash withdrawal
    2. The system establishes a connection with the Bank
    3. The system retrieves client's available account types
    4. The system displays available account types
    5. The client chooses a desired account type
    6. The client enters the amount to withdraw
    7. The system retrieves the selected account balance from the Bank
    8. The system validates available funds against account balance (see computation a in the Rules section below)
    9. The system prompts for confirmation
    10. The client confirms withdrawal amount
    11. The system computes new balance (see computation b in the Rules section below)
    12. The system disconnects from the Bank
    13. The system disperses specified amount
    14. The system prompts that cash is dispersed
    15. 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:
    1. The system prompts the client that the withdrawal amount exceeds the account balance
    2. The system displays available account types
  8. Exceptions:
    1. No available account types: The system prompts that "No available account types exit"
    2. Requested amount exceeds account balance: The system prompts that "The requested amount exceeds account balance"
  9. Rules:
    1. Available funds computation: Withdrawal amount must be less than or equal to account balance
    2. 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
    1. The system validates the password and the password is incorrect
    2. The system increments invalid login count by 1
    3. The system notifies the client that the password is incorrect
    4. The system prompts for password
  8. Exceptions:
    1. Bank card is disabled
    2. Account is locked
    3. Bank card is reported stolen
    4. Password is incorrect
  9. 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 <expiration date>"

               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.

References

  1. Software Requirements, 2nd Edition by Karl E. Wiegers (Microsoft Press, 2004)
  2. Mastering the Requirements Process, 2nd Edition by Suzanne Robertson and James Robertson (2006)
  3. Writing Effective Use Cases by Alistair Cockburn (2000)

About the Author

Aleksey Shevchenko has been working with object-oriented languages for over seven years. For the past four years, he has served as a technical lead and a project manager. Aleksey has been implementing Enterprise IT solutions for Wall Street and the manufacturing and publishing industries.

Sitemap | Contact Us

Thanks for your registration, follow us on our social networks to keep up-to-date