Crisp Requirements that deliver results!

Requirements Elicitation is a core skill for any business analyst or Product Manager. Broadly speaking, we can divide requirements into functional and non functional specifications delivered traditionally in form of business requirements document, technical specifications and usability designs. Over the last couple of decades with the widespread uptake of Agile, the way we write and communicate requirements has changed significantly, however, the key principles remain the same.

1. Characteristics of Good Requirements

A requirement needs to meet several criteria to be considered a “good requirement”. Good requirements should have the following characteristics:

• Unambiguous
• Testable (verifiable)
• Clear (concise, terse, simple, precise)
• Correct
• Understandable
• Feasible (realistic, possible)
• Independent
• Atomic
• Necessary
• Implementation-free (abstract)

Besides these criteria for individual requirements, three criteria apply to the set of requirements. The set should be

• Consistent
• Nonredundant
• Complete

Let’s discuss each of the criteria of a good requirement and show some examples.

1a. Unambiguous

There should be only one way to interpret the requirement. Sometimes ambiguity is introduced by undefined acronyms:

• REQ1 The system shall be implemented using ASP.

Does ASP mean Active Server Pages or Application Service Provider? To fix this, we can mention a full name and provide an acronym in parentheses:

• REQ1 The system shall be implemented using Active Server Pages (ASP).

Here’s another example:

• REQ1 The system shall not accept passwords longer than 15 characters.

It is not clear what the system is supposed to do:

• The system shall not let the user enter more than 15 characters.
• The system shall truncate the entered string to 15 characters.
• The system shall display an error message if the user enters more than 15 characters.

The corrected requirement reflects the clarification:

• REQ1 The system shall not accept passwords longer than 15 characters. If the user enters more than 15 characters while choosing the password, an error message shall ask the user to correct it.

Some ambiguity may be introduced through the placement of a certain word:

• REQ1 On the “Stored Flight” screen, the user can only view one record.

Does this mean that the user can “only view,” not delete or update, or does it mean that the user can view only one record, not two or three?

One way to fix the problem is to rewrite the requirement from the system’s point of view:

• REQ1 On the “Stored Flight” screen, the system shall display only one flight.

1b. Testable (Verifiable)

Testers should be able to verify whether the requirement is implemented correctly. The test should either pass or fail. To be testable, requirements should be clear, precise, and unambiguous. Some words can make a requirement untestable:

• Some adjectives: robust, safe, accurate, effective, efficient, expandable, flexible, maintainable, reliable, user-friendly, adequate
• Some adverbs and adverbial phrases: quickly, safely, in a timely manner
• Nonspecific words or acronyms: etc., and/or, TBD

Such a requirement might look something like this:

• REQ1 The search facility should allow the user to find a reservation based on Last Name, Date, etc.

In this requirement, all search criteria should be explicitly listed. The designer and developer cannot guess what the user means by “etc.”

Other problems can be introduced by ambiguous words or phrasing:

• Modifying phrases: as appropriate, as required, if necessary, shall be considered
• Vague words: manage, handle
• Passive voice: the subject of the sentence receives the action of the verb rather than performing it
  • REQ1 The airport code shall be entered by the user.
  • REQ2 The airport code shall be entered.

The first example shows a classic example of passive voice. In active voice it would read “The user shall enter the airport code.” As the second example shows, another result of the use of passive voice is that the agent performing the action is sometimes omitted. Who should enter this code—the system or the user?

• Indefinite pronouns: few, many, most, much, several, any, anybody, anything, some, somebody, someone, etc.
  • REQ1 The system shall resist concurrent usage by many users.

What number should be considered “many”—10, 100, 1,000?

1c. Clear (Concise, Terse, Simple, Precise)

Requirements should not contain unnecessary verbiage or information. They should be stated clearly and simply:

• REQ1 Sometimes the user will enter Airport Code, which the system will understand, but sometimes the closest city may replace it, so the user does not need to know what the airport code is, and it will still be understood by the system.

This sentence may be replaced by a simpler one:

• REQ1 The system shall identify the airport based on either an Airport Code or a City Name.

1d. Correct

If a requirement contains facts, these facts should be true:

• REQ1 Car rental prices shall show all applicable taxes (including 6% state tax).

The tax depends on the state, so the provided 6% figure is incorrect.

1e. Understandable

Requirements should be grammatically correct and written in a consistent style. Standard conventions should be used. The word “shall” should be used instead of “will,” “must,” or “may.”

1f. Feasible (Realistic, Possible)

The requirement should be doable within existing constraints such as time, money, and available resources:

• REQ1 The system shall have a natural language interface that will understand commands given in English language.

This requirement may be not feasible within a short span of development time.

1g. Independent

To understand the requirement, there should not be a need to know any other requirement:

• REQ1 The list of available flights shall include flight numbers, departure time, and arrival time for every leg of a flight.
• REQ2 It should be sorted by price.

The word “It” in the second sentence refers to the previous requirement. However, if the order of the requirements changes, this requirement will not be understandable.

1h. Atomic

The requirement should contain a single traceable element:

• REQ1 The system shall provide the opportunity to book the flight, purchase a ticket, reserve a hotel room, reserve a car, and provide information about attractions.

This requirement combines five atomic requirements, which makes traceability very difficult. Sentences including the words “and” or “but” should be reviewed to see if they can be broken into atomic requirements.

1i. Necessary

A requirement is unnecessary if

• None of the stakeholders needs the requirement.

or

• Removing the requirement will not affect the system.

An example of a requirement that is not needed by a stakeholder is a requirement that is added by developers and designers because they assume that users or customers want it. For example, the fact that a developer thinks that users would like a feature that displays a map of the airport and he knows how to implement it is not a valid reason to add this requirement.

An example of a requirement that can be removed because it does not provide any new information might look like the following:

• REQ1 All requirements specified in the Vision document shall be implemented and tested.

1j. Implementation-free (Abstract)

Requirements should not contain unnecessary design and implementation information:

• REQ1 Content information shall be stored in a text file.

How the information is stored is transparent to the user and should be the designer’s or architect’s decision.

1k. Consistent

There should not be any conflicts between the requirements. Conflicts may be direct or indirect. Direct conflicts occur when, in the same situation, different behavior is expected:

• REQ1 Dates shall be displayed in the mm/dd/yyyy format.
• REQ2 Dates shall be displayed in the dd/mm/yyyy format.

Sometimes it is possible to resolve the conflict by analyzing the conditions under which the requirement takes place. For example, if REQ1 was submitted by an American user and REQ2 by a French user, the preceding requirements may be rewritten as follows:

• REQ1 For users in the U.S., dates shall be displayed in the mm/dd/yyyy format.
• REQ2 For users in France, dates shall be displayed in the dd/mm/yyyy format.

This can eventually lead to the following requirement:

• REQ3 Dates shall be displayed based on the format defined in the user’s web browser.

Another example of a direct conflict can be seen in these two requirements:

• REQ1 Payment by PayPal shall be available.
• REQ2 Only credit card payments shall be accepted.

In this case the conflict cannot be resolved by adding conditions, so one of the requirements should be changed or removed.

Indirect conflict occurs when requirements do not describe the same functionality, but it is not possible to fulfill both requirements at the same time:

• REQ1 System should have a natural language interface.
• REQ2 System shall be developed in three months.

Some requirements do not conflict, but they use inconsistent terminology:

• REQ1 For outbound and inbound flights, the user shall be able to compare flight prices from other, nearby airports.
• REQ2 The outbound and return flights shall be sorted by the smallest number of stops.

To describe the same concept, in the first requirement the term “inbound flights” is used, and in the second requirement the term “return flights” is used. The usage should be consistent.

1l. Nonredundant

Each requirement should be expressed only once and should not overlap with another requirement:

• REQ1 A calendar shall be available to help with entering the flight date.
• REQ2 The system shall display a pop-up calendar when entering any date.

The first requirement (related to only the flight date) is a subset of the second one (related to any date entered by the user).

1m. Complete

A requirement should be specified for all conditions that can occur:

• REQ1 A destination country does not need to be displayed for flights within the U.S.
• REQ2 For overseas flights, the system shall display a destination country.

What about flights to Canada and Mexico? They are neither “within the U.S.” nor“overseas.”

All applicable requirements should be specified. This is the toughest condition to be checked. There is really no way to be sure that all the requirements are captured and that one week before the production date one of the stakeholders won’t say, “I forgot to mention that I need one more feature in the application.”

A good requirement should have more criteria. However, they usually can be expressed as a combination of the criteria we have just discussed:

• Modifiable: If it is atomic and nonredundant, it is usually modifiable.
• Traceable: If it is atomic and has a unique ID, it is usually traceable.

2. Common Problems

The following is a list of the most common problems in writing requirements:

• Making bad assumptions
• Writing implementation (HOW) instead of requirements (WHAT)
• Describing operations instead of writing requirements
• Using incorrect terms
• Using incorrect sentence structure or bad grammar
• Missing requirements
• Over-specifying

Each of these is discussed in detail below.

2a. BAD ASSUMPTIONS

Bad assumptions occur either because requirement authors do not have access to sufficient information or the information does not exist. You can eliminate the first problem by documenting the information critical to the program or project, including:

• Needs
• Goals
• Objectives
• Constraints
• Missions
• Operations Concept
• Budget
• Schedule
• Management/Organization

This information then must be made available to all authors. You can create and maintain a list of other relevant documents and make these easily accessible to each author. If you have automated the process, you can offer documents on-line and you can filter the information within the documents so that individual authors can get copies of only the data that they need.

In the second case where information does not exist, the requirement author should document all assumptions with the requirement. When the requirement is reviewed, the assumptions can also be reviewed and problems quickly identified. It is also useful to document the assumptions even if the authors were provided the correct information. You cannot ensure that all authors have read all the information or interpreted it correctly. If they document their assumptions, you will avoid surprises later.

2b. IMPLEMENTATION

A specification was released for the development of a requirements management tool. The first requirement was to “provide a data base”. The statement is one of implementation and not of need, and it is common to find such statements in requirement specifications. Specifications should state WHAT is needed, not HOW it is to be provided. Yet this is a common mistake made by requirement writers. Most authors do not intend to state implementation; they simply do not know how to state the need correctly.

To avoid stating implementation, ask yourself WHY you need the requirement. In the example cited, it can be seen that by asking WHY, the author can define all of the needs that the system must meet and will then state the real requirements, e.g.:

• Provide the capability for traceability between requirements
• Provide the capability to add attributes to requirements
• Provide the ability to sort requirements.

These requirements state WHAT is needed, not HOW to accomplish it. Each of the above listed requirements might result in a data base type of system, but the requirement for the database was not needed.

There are two major dangers in stating implementation. The one most often cited is that of forcing a design when not intended. If all the needs can be met without a database, then why state the need for a database. If they cannot be met, another, or better way, then a database will be the solution — whether or not there was a requirement for a database.

The second danger is more subtle and potentially much more detrimental. By stating implementation, the author may be lulled into believing that all requirements are covered. In fact, very important requirements may be missing, and the provider can deliver what was asked for and still not deliver what is wanted. Providing a database will not be sufficient for someone needing a requirements management tool. It is the capabilities of the tool that need to be stated as requirements.

At each level of requirements development the problem of needs versus implementation will occur. At the system level the requirements must state WHAT is needed. The system designer will determine HOW this can be accomplished and then must define WHAT is needed at the subsystem level. The subsystem designer will determine HOW the need can be met and then must define WHAT is needed at the component level.

To ensure that you have not stated implementation, ask yourself WHY you need the requirement. If this does not take you back to a real need statement, then you are probably stating a need and not implementation.

The Implementation Trap. If you have been doing design studies at a low level, you may begin to document these results as high-level requirements — this is the implementation trap. You will be defining implementation instead of requirements.

An example of this occurred during the definition of the Assured Crew Return Vehicle (ACRV) requirements. An individual submitted a requirement like this:

The ACRV System shall enter when sea state is at TBD conditions.

The ACRV had no requirement for a water landing — that was a design option. The individual had been working with that design option, and from previous Apollo experience known that crew rescue was possible only in certain sea states.

When asked WHY the requirement was needed, the individual stated that the crew could not be left in the module for a lengthy period of time, thus the landing needed to be where and when sea states could accommodate crew rescue. He had a valid requirement — but not the one he had written. Whether the ACRV landed on water or land, removing the crew within a limited time period was essential. Thus the real requirement was:

The ACRV System shall provide for crew removal within TBD time of landing.

The question WHY will resolve most implementation requirement errors. Always ask WHY a requirement is needed to insure that you have not fallen into this lower level requirement trap.

2c. OPERATIONS VS. REQUIREMENTS

This problem is somewhat similar to the implementation problem. The Simplified Aid for EVA Rescue (SAFER) project provides examples of this problem.

The author intended to write an environment requirement in the SAFER Flight Test Article (FTA) Specification. The statement was written as a description of operations, not a requirement about the environment.

The SAFER FTA shall be stowed in the Orbiter Airlock Stowage Bag for launch landing, and on-orbit stowage.

The real requirement is:

The SAFER FTA shall be designed for the stowage environment of the Airlock Storage Bag for launch, entry, landing, and on-orbit, as defined in TBD.

The next requirement again describes the operations and is confusing.

The SAFER FTA shall be operated by an EVA Crew member wearing EMU sizes small through extra large without limiting suit mobility.

The statement was rewritten and resulted in a requirement and a design goal. The design goal is needed because no quantifiable requirement can be written regarding suit mobility.

The SAFER FTA shall be designed for use with EMU sizes small through extra large.

The SAFER FTA should not limit EVA crewmember mobility.

The danger in stating operations, instead of a requirement is (1) the intent may be misunderstood and (2) determining how to verify can be a problem.

2d. USE OF TERMS

In a specification, there are terms to be avoided and terms that must be used in a very specific manner. Authors need to understand the use of shall, will, and should:

• Requirements use shall
• Statements of fact use will
• Goals use should.

These are standard usage of these terms in government agencies and in industry. You will confuse everyone if you deviate from them. All shall statement (requirements) must be verifiable, otherwise, compliance cannot be demonstrated.

Terms such as are, is, was, and must do not belong in a requirement. They may be used in a descriptive section or in the lead-in to a requirements section of the specification

There are a number of terms to be avoided in writing requirements, because they confuse the issue and can cost you money, e.g.

• Support
• But not limited to
• Etc.
• And/Or

The word support is often used incorrectly in requirements. Support is a proper term if you want a structure to support 50 pounds weight. It is incorrect if you are stating that the system will support certain activities.

WRONG: The system shall support the training coordinator in defining training scenarios.RIGHT: The system shall provide input screens for defining training scenarios. The system shall provide automated training scenario processes.

The terms but not limited to, and Etc. are put in place because the person writing the requirements suspects that more may be needed than is currently listed. Using these terms will not accomplish what the author wants and can backfire.

The reason the terms are used is to cover the unknown. The contractor will not increase the cost in the proposal because you added these terms. The only way to get the work added is to place an analysis task in the Statement of Work (SOW) to determine if more items need to be added to the list. In the SOW you can control what effort the contractor will expend to address these unknowns. If more items are found, you may have to increase the scope of the contract to cover the additions.

If you have these terms in your requirements specification, the contractor may use them as an excuse for doing unnecessary work for which you must pay. You cannot win by using the terms in the specification.

The term and/or is not appropriate in a specification. If you use and/or and the contractor does the or, he has met the terms of the contract. Either you want item 1 and item 2 or you will be satisfied with item 1 or item 2. Again, if you use the term or, then the contractor has met the terms of the contract if he does either item.

2e. REQUIREMENT STRUCTURE/GRAMMAR

Requirements should be easy to read and understand. The requirements in a system specification are either for the system or its next level, e.g. subsystem. Each requirement can usually be written in the format:

• The System shall provide …
• The System shall be capable of …
• The System shall weigh …
• The Subsystem #1 shall provide …
• The Subsystem #2 shall interface with …

Note: The name of your system and the name of each subsystem appear in these locations. If you have a complex name, please use the acronym, or your document will have many unneeded pages just because you have typed out a long name many times.

Each of these beginnings is followed by WHAT the System or Subsystem shall do. Each should generally be followed by a single predicate, not by a list. There are situations where a list is appropriate, but lists are over-used. Since each item in the list must be verified, unless all items will be verified by the same method and at the same time, it is generally not appropriate to put items in a list.

Requirement statements should not be complicated by explanations of operations, design, or other related information. This non-requirement information should be provided in an introduction to a set of requirements or in rationale.

You can accomplish two things by rigorously sticking to this format. First, you avoid the Subject Trap. Second, you will avoid bad grammar that creeps into requirements when authors get creative in their writing.

Subject Trap. A system specification contains requirements for the system, e.g., you may want to require that the system provide control. A set of requirements might be written that reads as follows:

• The guidance and control subsystem shall provide control in six degrees of freedom.
• The guidance and control subsystem shall control attitude to 2+/- 0.2 degrees.
• The guidance and control subsystem shall control rates to 0.5 +/- 0.05 degrees/second.

The subject trap is created because the author has defined a guidance and control subsystem. Controlling attitude and rate is a system problem; it requires not only a guidance and control subsystem but also a propulsion subsystem to achieve these attitudes and rates. Determining what subsystems will be required to accomplish the requirements is part of the design process. The requirements should be written from the system perspective, as follows:

• The system shall provide six degrees of freedom control.
• The system shall control attitude to 2 +/- 0.2 degrees.
• The system shall control rates to 0.5 +/- 0.05 degrees/second.

The author of the original requirements was not trying to define the lower level breakout. He probably comes from a control background and sees the system from that perspective and hence writes requirements that way. The flow down of requirements, to all affected segments, elements, and subsystem, will be badly affected if these requirements are not written correctly.

Bad Grammar. If you use bad grammar you risk that the reader will misinterpret what is stated. If you use the requirements structure suggested above, you will eliminate the bad grammar problems that occur when authors try to write complex sentences and use too many clauses.

Another solution is to write requirements as bullet charts. When the content is agreed upon a good writer can convert the information into a sentence for the specification.

Authors will also try to put all that they know in a single sentence. This results in a long complex sentence that probably contains more than one requirement. Bullet charts or one good editor can alleviate this problem. The following requirement contains multiple requirements.

The ACRV System shall provide special medical life-support accommodations for one ill or injured crew member consisting of medical life-support and monitoring equipment and the capability of limiting impact accelerations on that crew member to be not greater than… for a total impulse not to exceed …

The requirement needs to be broken into at least four requirements and it could use a lead-in such as:

The ACRV will be used as an ambulance for an ill or injured crewmember. Only one crewmember will be accommodated at a time. The following define the unique requirements for this capability.

• …Provide medical life-support accommodations for one crew member
• …Provide monitoring equipment for one crew member
• …Limit impact accelerations to the ill or injured crew member to no greater than…
• …Limit total impulse to the ill or injured crew member to…

2f. UNVERIFIABLE

Every requirement must be verified.

Because every requirement must be verified, it is important to address verification when writing the requirements. Requirements may be unverifiable for a number of reasons. The following discusses the most common reason — use of ambiguous terms.

Ambiguous Term. A major cause of unverifiable requirements is the use of ambiguous terms. The terms are ambiguous because they are subjective — they mean something different to everyone who reads them. This can be avoided by giving people words to avoid. The following lists ambiguous words that we have encountered.

• Minimize
• Maximize
• Rapid
• User-friendly
• Easy
• Sufficient
• Adequate
• Quick

The words maximize and minimize cannot be verified, you cannot ever tell if you got there. The words minimum and maximum may be used if the context in which they are used can be verified.

What is user-friendly and what is rapid? These may mean one thing to the user or customer and something entirely different to a designer. When you first begin writing your requirements, this may be what you are thinking, but you must write the requirements in terms that can be verified. If you must use an ambiguous term in first draft documents, put asterisks on either side of the term to remind yourself that you are going to have to put something concrete in the requirement before you baseline the document.

There may be cases where you cannot define, at your level, exactly what is needed. If this is the case, then you should probably be writing a design goal, not a requirement. You can do this by clearly indicating that your statement is a goal, not a requirement. Use of the word should, instead of shall, will denote a design goal.

2g. MISSING

Missing items can be avoided by using a standard outline for your specification, such as those shown in Mil-Std-490 or IEEE P1233, and expanding the outline for your program.

Many requirements are missed because the team writing the requirements is focused on only one part of the system. If the project is to develop a payload, the writers will focus on the payload’s functional and performance requirements and perhaps skip other important, but less obvious, requirements. The following is a checklist of requirement drivers you need to consider:

• Functional · Reliability
• Performance · Maintainability
• Interface · Operability
• Environment · Safety
• Facility · Regulatory
• Transportation · Security
• Deployment · Privacy
• Training · Design constraints
• Personnel

You will need to develop detailed outlines for your specification for the functional and performance requirements, and in perhaps other areas.

You may also have a number of requirements that you must include by reference. In particular, those standards that define quality in different disciplines (materials and processes) or for different projects.

Detailed requirements analysis is necessary to assure that all requirements are covered. There are a number of approaches to performing requirements analysis and a number of tools for doing this work. Detailed requirements analysis is beyond the scope of this paper.

2h. OVER-SPECIFYING

The DoD has stated that over-specification is the primary cause of cost overruns on their programs. Over-specifying is most often from stating something that is unnecessary or from stating overly stringent requirements.

Unnecessary Items. Unnecessary requirements creep into a specification in a number of ways. The only cure is careful management review and control.

People asked to write requirements would write down everything they can think of. If you do not carefully review each requirement and why it is needed before base lining the specification, the result will be a number of unneeded requirements.

Example: The Space Station Training Facility (SSTF) had a requirement for a high-fidelity star field. The author knew that a new high-fidelity star field was being developed for the Shuttle Mission Simulator (SMS) and assumed they might as well put the same thing in the SSTF. The crew needs a background to view outside the Space Station, but there is no need for a high-fidelity star field, since they do not use the stars for navigation.

The requirement needs to be written for a visual background for crew orientation. The design process will determine if using the SMS star field is a cost effective solution or it something simpler is adequate and more cost effective.

Example: A number of SSTF requirements were deleted when their authors were queried as to the need. The need they stated was that “it would be nice to have”. Most program do not have budgets for nice to have items.

Unnecessary requirements can also appear after baseline if you let down your review and control process. In ACRV a number of requirements were added after the initial baseline that were not needed. One such instance occurred because of an error in the baseline document.

Example: The baseline document had two requirements:

The ACRV System shall be capable of operating over a planned operational life of thirty (30) years.

The Flight Segment shall provide an operational life of 30-years for the flight elements.

The second requirement, for the Flight Segment, was not required since the System requirement was adequate. The action that should have been taken was to delete the Flight Segment requirement. Instead, two more requirements were added to require a 30-year operational life of the other two segments.

At least one other requirement was added to ACRV that was a duplicate of an existing requirement. The wording of the two differed only slightly and their rationale was the same. It requires careful attention to detail to avoid this type of problem.

Over Stringent. Most requirements that are too stringent are that way accidentally, not intentionally. A common cause is when an author writes down a number but does not consider the tolerances that are allowable.

Thus, you should not state that something must be a certain size, e.g., 100 ft.², if it could just as easily be 100 +/- 10 ft.². You do not need to ask that something deliver a payload to exactly 200 n.m. if greater than or equal to 200 n.m. is acceptable.

Some of the major horror stories of the aerospace industry deal with overly stringent requirements. One contractor was severely criticized for charging $25,000 per coffee pot in airplanes built for the government. But the requirements for the coffee pot were so stringent, that the plane could have crashed and yet no coffee could spill. It cost a great deal to develop the coffee pot and to verify that it met its requirements. Each copy had to be built to a stringent design.

The solution to this problem is to discuss the tolerances allowable for any value and then to write the requirement to take into consideration those tolerances. Each requirement’s cost should also be considered.

3. Requirements Pyramid

Depending on the format, source, and common characteristics, the requirements can be split into different requirement types. Here are some requirement types that are often used in projects:

• Stakeholder need: a requirement from a stakeholder
• Feature: a service provided by the system, usually formulated by a business analyst; a purpose of a feature is to fulfill a stakeholder need
• Use case: a description of system behavior in terms of sequences of actions
• Supplementary requirement: another requirement (usually nonfunctional) that cannot be captured in use cases
• Test case: a specification of test inputs, execution conditions, and expected results
• Scenario: a specific sequence of actions; a specific path through a use case

It is up to business analysts to decide on the granularity of requirements at each level. Nothing is wrong with placing quite detailed requirements from stakeholders on the stakeholder needs level.

The main difference between needs and features is in the source of the requirement. Needs come from stakeholders, and features are formulated by business analysts.

4. Traceability is the key!

Traceability is a technique that provides a relationship between different levels of requirements in the system. This technique helps you determine the origin of any requirement. Every need usually maps to some features. Generally, it is a many-to-many relationship because one need can trace to many features, but one feature may be derived from many needs. One need mapping to one feature is also a common case. The features map to use cases in a many-to-many relationship. The features also map to supplementary requirements in a many-to-many relationship.

Every use case maps to one or more scenarios, so a one-to-many relationship exists between use cases and scenarios. Scenarios map to test cases in a one-to-many relationship.

Traceability plays several important roles:

• Verifying that an implementation fulfills all requirements: Everything that the customer requested was implemented.
• Verifying that the application does only what was requested: Don’t implement something that the customer never asked for.
• Impact analysis: What elements will be affected when we consider adding a new requirement or changing an existing one?
• Helping with change management: When some requirements change, we want to know which test cases should be redone to test this change.

A traceability item is a project element that needs to be traced from another element. In terms of RequisitePro, it’s everything that is represented by an instance of the requirement type. Some examples of requirement types in RequisitePro are stakeholder needs, features, use cases, actors, and glossary terms. RequisitePro has a convenient way of showing traceability in special views.

5. The Process is the king

A simplified description of the requirements management process contains the following major steps:

• Establishing a requirements management plan
• Requirements elicitation
• Developing the Vision document
• Creating use cases
• Supplementary specification
• Creating test cases from use cases
• Creating test cases from the supplementary specification
• System design

The first step (requirements management plan) defines the requirements pyramid. In each of the next seven steps, one of the elements of the pyramid is built. Table 1.1 describes which requirement types and what documents are created in each step. As you can see, the process navigates through the pyramid from the top down and from left to right.

5a. An Overview of the Requirements Management Process

A simplified description of the requirements management process contains the following major steps:

• Establishing a requirements management plan
• Requirements elicitation
• Developing the Vision document
• Creating use cases
• Supplementary specification
• Creating test cases from use cases
• Creating test cases from the supplementary specification
• System design

The first step (requirements management plan) defines the requirements pyramid. In each of the next seven steps, one of the elements of the pyramid is built. Table 1.1 describes which requirement types and what documents are created in each step. As you can see, the process navigates through the pyramid from the top down and from left to right.

Table 1.1 Requirements and Documents Created in Each Phase

Requirements management is an interactive process. In a typical iteration, a full pass through the pyramid is performed. Even in the same iteration, we can go back a few steps and repeat the activity. For example, during the creation of a test case, we can discover that some information is missing, and we need more input from a stakeholder, so we go back a step to “gathering requirements.” To maintain the model’s integrity, it is important to update all affected requirements. In initial iterations the emphasis is placed on the first few steps (the top of the pyramid), and in later iterations more time is spent on the lower part of the pyramid.

Let’s briefly look through all the steps.

5b. Establishing a Requirements Management Plan

One of the first tasks in the project is developing a Requirements Management Plan (RMP). The RMP describes the overall approach to managing requirements in the project. The document details how requirements are created, organized, modified, and traced during the project lifecycle. It also describes all requirement types and their attributes used in the project.

Here are some questions that can be answered in the RMP:

• Will any RM tool be used?
• What requirement types will be tracked in the project?
• What are the attributes of these requirements?
• Where will the requirements be created—in the database only or in the documents?
• Between which requirements do we need to implement traceability?
• What documents are required?
• Which requirements and documents will be used as a contract with customers?
• If part of the project is outsourced, what requirements and documents will be used as a contract with a vendor?
• Will we follow the RUP or some other methodology?
• Does the customer need any specific documents to comply with his development process?
• How will change management be implemented?
• Assuming that RequisitePro is used, will the whole system be stored in one RequisitePro project or spread among many projects?
• What process will guarantee that all requirements were implemented and tested?
• Which requirements or views do we need to generate reports?

Chapter 3, “Establishing a Requirements Management Plan,” describes all these decisions in detail.

5c. Requirements Elicitation

Requirements elicitation, also called requirements gathering, is a very important step. Missing or misinterpreting a requirement at this stage will propagate the problem through the development lifecycle.

Here are some of the techniques used to elicit requirements from stakeholders:

• Interviews
• Questionnaires
• Workshops
• Storyboards
• Role-playing
• Brainstorming sessions
• Affinity diagrams
• Prototyping
• Analysis of existing documents
• Use cases
• Analysis of existing systems

These techniques are described in Chapter 5, “Requirements Elicitation.”

5d. Developing the Vision Document

During development of the Vision document, one of the main goals of business analysts is deriving features from stakeholder needs. Features should have all the attributes of a good requirement. They should be testable, nonredundant, clear, and so on.

The Vision document should contain essential information about the system being developed. Besides listing all the features, it should contain a product overview, a user description, a summary of the system’s capabilities, and other information that may be required to understand the system’s purpose. It may also list all stakeholder needs in case they were not captured in separate documents.

Some parts of the Vision are created at the very beginning, before we even start eliciting requirements from stakeholders. Examples of these sections are

• A description of the problem being solved.
• Identification of users/customers/stakeholders.

5e. Creating Use Cases

Functional requirements are best described in the form of use cases. They are derived from features.

Use cases are derived from features that describe the system’s functionality. Scenarios are derived from use cases.

A use case is a description of a system in terms of a sequence of actions. It should yield an observable result or value for the actor (an actor is someone or something that interacts with the system). The use cases

• Are initiated by an actor.
• Model an interaction between an actor and the system.
• Describe a sequence of actions.
• Capture functional requirements.
• Should provide some value to an actor.
• Represent a complete and meaningful flow of events.

Here is a fragment of a use case:

1. The user enters required flight information: departure airport and date, arrival airport and date.
2. The system displays all outbound flights matching the search criteria.
3. The user selects an outbound flight.
4. The system displays a list of available return flights.

The purpose of a use case is to facilitate agreement between developers, customers, and users about what the system should do. A use case becomes sort of a contract between developers and customers. It’s also a basis for use case realizations, which play a major role in design. In addition, you can produce sequence diagrams, communication diagrams, and class diagrams from use cases. Furthermore, you can derive user documentation from use cases. Use cases may also be useful in planning the technical content of iterations and give system developers a better understanding of the system’s purpose. Finally, you can use them as an input for test cases.

While designing use cases we will also define scenarios—specific paths through the use case. We usually implement systems scenario by scenario, not the whole use case at once. Scenarios are required when we derive test cases from use cases. On the requirements pyramid, scenarios are one level below use cases.

5f. Supplementary Specification

Supplementary specification captures nonfunctional requirements (usability, reliability, performance, supportability) and some functional requirements that are spread across the system, so it is tough to capture them in the use cases. These requirements are called supplementary requirements and are derived from features.

5g. Creating Test Cases from Use Cases

As soon as all the requirements are captured, we should design a way to check whether they are properly implemented in the final product. Test cases will show the testers what steps should be performed to test all requirements. In this step we will concentrate on creating test cases from use cases. If we did not create scenarios while generating use cases, we need to define them now. Test cases are at the lowest level of the pyramid.

5h. Creating Test Cases from the Supplementary Specification

The approach used in the preceding step does not apply to testing supplementary requirements. Because these requirements are not expressed as a sequence of actions, the concept of scenarios does not apply to them. An individual approach should be applied to each of the supplementary requirements because techniques used to test performance requirements are different from techniques used to test usability requirements. In this step we also design testing infrastructure and platform-related issues.

Sometimes we need to “borrow” one scenario that was created to test use cases. For example, to test the requirement “The system should run using the Internet Explorer (IE) browser and using the Netscape browser,” we should select one scenario (preferably basic flow of the most popular use case) and test the full scenario in the IE browser. Then we should test the same scenario again in the Netscape browser. There is no need to test all test cases created in the preceding step in both browsers. Just select those that contain some functionality that may be browser-specific.

5i. System Design

Requirements are the basis for system design, which is often facilitated by use of the Unified Modeling Language (UML) . Many tools, such as Rational Rose, Rational Software Architect, Rational Data Architect, and Rational Software Modeler, can significantly facilitate the creation of all required diagrams.

6. Agile Requirements

In the world of Agile, I recommend breaking requirements down as below:

• Business Requirements
• User Stories
• User flows, use cases and mockups

A good format for writing user stories is below:

Business Requirement: The system will facilitate the users to (a) keep their data secure and (b) only allow authenticated users to access homepage.

User Story:

As a <user>, I want to be able to <achieve this> so that, <benefit>.

As a registered user of the system, I want to be able to login to the system successfully, so that I can access my homepage to book appointments.

User Scenario:

Follow this up with Gherkin style user story details breaking down each scenario:

Scenario 1: <Title>

Give I am on <pre requisites>

When I <action>

Then <response>

As a user, I want to be able to successfully login to the system using my correct login credentials, so that I can access my homepage securely.

Scenario 1: Successful Login

Given I am on the login page

When I enter my correct username and passwprd

And hit the Login button

Then, I will be redirected to the homepage

Scenario 2: Uncessful Login

Given I am on the login page

When I enter my username and password

And hit the Login button

And my username and password combination is invalid

Then, I will remain on the login page

And, I will see an error message, “Your login credendials are incorrect”

And, the system will update the incorrect login counter by 1

Scenario 3: Multiple Unsuccessful Login Attempts

Given I am on the Login page

and I have already made two unsuccessful login attempts

When I enter my username and password

And hit the Login button

And my username and password combination is invalid

Then, I will remain on the login page

And, I will see an error message, “Your login credentials are incorrect. Your account has been locked because of multiple incorrect login attempts. Please contact customer support for assistance.

7. Go Visual!

A picture is a worth a thousand words. Use tools which help you illustrate requirements visually to communictae your vision in crisp details. My personal recommendation is to become a master at these tools and use them at all opportunities:

• Microsoft Visio for BPMN, UML Diagrams or Flow Charts (free web based alternatives available)
• Rapid Prototyping tools
• Low fidelity mockup tools (e.g., Moqups, Visio)
• Atlassian Confluence for business requirements
• Atlassian Jira for user stories
• create your own macro enabled spreadsheets for tracability between business requirements, user stories and test cases, as well as mockups.

More to follow…