Tag Archive for: karl wiegers

Software products are rarely delivered in final form with the first release. More commonly, they evolve through a series of releases or iterations that correct defects, add progressively more features, and enrich or update previously implemented features. This means that during requirements development you’ll be accumulating requirements that could be targeted for various releases. You need to determine the best way to store and manage these requirements so that no one is confused about the contents of each upcoming release.

A related issue pertains to requirements that were proposed, but never approved. Similarly, you might approve certain requirements for a specific release, only to delete them later (perhaps deferring them to a future release or iteration) either because they are no longer valuable or because of time and resource limitations. Deleted requirements, rejected requirements, ideas, and potential requirements for the future have a way of resurfacing before the project is finished. You don’t want to lose sight of the fact that these requirements once were proposed or considered to be in scope. Nor do you want anyone to work on them under the mistaken belief that they’re intended for the next release.

There are several ways to deal with requirements that are not a part of the current build. The goal is to produce specifications that clearly identify the requirements for each release, while still providing access to all requirements that describe the historical and possible future states of the product. This article compares three strategies for solving this problem:

• Storing all requirements in a single software requirements specification (SRS).

• Creating a separate SRS for each release.

• Storing requirements in a requirements management tool.

Single Requirements Specification

One option is to begin by writing an SRS that contains just those requirements that are planned for the initial product release. This approach makes sense if your team is continuously working on the next set of prioritized requirements and modifications in the backlog, creating a release whenever they have a bundle of enhancements and changes ready to go. When you think the initial SRS is complete, define it as a baseline for that first release. Store the baselined document in a version control tool. Then use check-in and check-out procedures to make changes to the SRS and maintain a revision history of changes made.

As you identify new or modified requirements for any planned release, highlight those changes using your word processor’s revision marks feature. Indicate the planned release number so everyone will know which requirements are in scope for each release. Also, explicitly identify those requirements that have been deleted or that were proposed once but not approved, along with an explanation of why each decision was made. This retains those requirements for possible future use.

After you’ve recorded all the requirements you intend to implement in the next release, take the following actions:

1. Archive the SRS in the version control tool, with the revision marks included to identify changes made since the previous version of the document was baselined.

2. Create a copy of the marked-up file. Accept all the revisions, thereby making all the requirements and changes made to them current. Save that version in your version control tool, too. Identify this document as now representing the full set of requirements for the specified product release, including all functionality that was implemented in previous releases.

3. Continue the process of entering changes with revision marks turned on and periodically baselining the SRS for each subsequent release.

This approach results in developing a single master SRS that contains all the requirements that fully describe your product as it grows through multiple releases. The revision marks in any single historical version represent just the deltas from the previous version.

Creating a master SRS provides the advantage of collecting all the requirements in a single place. You can place new requirements placed in context wherever they belong. It’s also easy to handle requirements that were originally planned for a future release but have moved into scope for the current release. Because these requirements are already in the document, it’s just a matter of indicating that they are now planned for the upcoming release.

The single-spec approach has some shortcomings, though. It’s easy to get confused about which requirements the developers are supposed to implement in a specific release. It’s also difficult to view just the subset of the requirements that describe a specific incremental release because the requirements for multiple releases are all threaded together. Suppose that for release 5 you have 23 new requirements sprinkled throughout your 50-page master SRS. Developers and testers will need to print the entire document and study the revision marks to figure out exactly what to do. This is inefficient and error-prone.

Multiple Requirements Specifications

If your organization treats each new product release as a separate project, consider writing a separate SRS for each such release. This can also work in an iterative environment, treating each iteration as a micro-project. The SRS for the first release should follow a comprehensive SRS template, such as the one available from http://www.processimpact.com/goodies.shtml. Much of this information will remain unchanged for future releases.

Each incremental SRS for a subsequent release will be simpler than the first one, without all the global and background information that appeared in the initial SRS. Each incremental SRS will describe just those functional requirements that are being added or changed, along with associated performance requirements, other quality attributes, and business rules. Consider using different document templates for the comprehensive initial SRS and for the smaller and simpler incremental specs.

If you create multiple specifications in this way, then you can use each separate document to describe exactly what the team is going to do in a particular release. This is more reliable than hoping that every reader will correctly glean all the changes from an increasingly bulky master SRS. Individual specifications are smaller, less intimidating, and easier to work with, especially in hard copy form.

Creating multiple specifications presents some disadvantages, though. Shifting a requirement from one planned release to another requires that you actually move the text describing that requirement from one document to another. Writing a separate SRS for each release doesn’t provide the context and big-picture synthesis of what the whole product is today. Someone who wants to get a complete description of any feature, let alone the entire product, has to assemble bits of information from multiple sources. With multiple specifications, it’s also easy to lose track of those requirements that were not allocated to a particular product release and yet remain in the backlog of possible future work. There’s no logical place to put them, unless you create yet another document to contain the “leftover” requirements that might be of future interest.

Requirements Management Tool

The most robust strategy is to store the requirements in the database of a commercial requirements management tool. This keeps the requirements for all releases stored together. You can use the tool’s baseline-definition feature to distinguish the subsets of requirements that belong to different releases. Alternatively, you could define a requirement attribute to hold the planned release number for each requirement. Reallocating a requirement from one release to another then becomes a simple matter of changing this attribute. A status attribute helps you distinguish rejected or deleted requirements from the others.

When you store requirements in a tool, an SRS becomes a report generated from the database contents according to specific query and filter criteria. You have several options:

• To see a complete specification for the entire product to date, extract all the requirements for the current version and all previous releases.

• To see the specification for a single release, report just the requirements allocated to that release.

• To see the requirements that were proposed but rejected, or those that never made it into the product in the first place, base your query on the appropriate values of the status attribute.

Requirements management tools overcome many of the limitations of document-based storage. For example, some tools will retain all historical versions of every individual requirement, whereas version control tools generally maintain previous versions of entire documents. Commercial RM tools let you store requirements in a single master location that is always current and is accessible via the Internet to authorized stakeholders. These products aren’t cheap, but their capabilities often outweigh the costs. You can find descriptions and feature comparisons of many commercial RM tools at http://www.incose.org/ProductsPubs/Products/rmsurvey.aspx and http://www.volere.co.uk/tools.htm. Chapter 23 of my book More about Software Requirements (Microsoft Press, 2006) provides recommendations for how to use requirement management tools effectively on a project.

As with so many of the other thorny issues about requirements, there is no perfect and simple solution to the matter of concurrently managing requirements for multiple product releases (or similarly, multiple variations of a single product). It’s most important that your project team determine in advance what techniques and tools it will use to deal with this situation, using the strategies I’ve described here as a starting point.

Jama Software has partnered with Karl Wiegers to share licensed content from his books and articles on our web site via a series of blog posts, whitepapers and webinars.  Karl Wiegers is an independent consultant and not an employee of Jama.  He can be reached at http://www.processimpact.com.  Enjoy these free requirements management resources.

 

The major consequence of requirements problems is rework—doing over something that you thought was already done. Rework can consume 30 to 50 percent of your total development cost, and requirements errors account for 70 to 85 percent of the rework cost. The data from Hewlett-Packard in Figure 1 shows that it costs far more to correct a defect that’s found late in the project than to fix it early on. Preventing requirements errors and catching them early therefore has a huge leveraging effect on reducing rework. Imagine how different your life would be if you could cut your rework effort in half! You could build products faster, build more and better products in the same amount of time, and perhaps even go home occasionally.

Figure 1. The relative cost to correct a requirement defect depends on when it’s discovered

Shortcomings in requirements practices pose many risks to project success. I describe some of the most common requirements risks in this post.

Insufficient User Involvement

Customers often don’t understand why it is so essential to work hard on gathering requirements and assuring their quality. Developers might not emphasize user involvement, either because working with users isn’t as much fun as writing code or because they think they already know what the users need. In some cases, it’s difficult to gain access to people who will actually use the product, and user surrogates don’t always understand what users really need. Insufficient user involvement leads to late-breaking requirements that delay project completion. There’s no substitute for having the development team work directly with actual users throughout the project.

Creeping Requirements

As requirements evolve and grow during development, projects often exceed their planned schedules and budgets. Such plans aren’t always based on realistic understandings of the size and complexity of the requirements; constant requirements modifications make the problem worse. The problem lies partly in the users’ frequent requests for changes in the requirements and partly in the way that developers respond to these requests.

To manage scope creep, begin with a clear statement of the project’s business objectives, strategic vision, scope, and success criteria. Evaluate proposed new requirements or changes against this reference. An effective change process that includes impact analysis will help the stakeholders make informed business decisions about which changes to accept and the associated cost. Change is often necessary, but change always has a price. To minimize quality degradation, flow requirements changes through the architecture and design rather than implementing them directly into code.

Ambiguous Requirements

One symptom of ambiguity is that a reader can interpret a requirement statement in several ways. Another sign is that multiple readers of a requirement arrive at different understandings of what it means. Ambiguity also results from imprecise and insufficiently detailed requirements that force developers to fill in the blanks. Ambiguous requirements result in wasted time when developers implement a solution for the wrong problem. Testers who expect the product to behave differently from what the developers intended waste time resolving the differences.

One way to ferret out ambiguity is to have people who represent different perspectives formally review the requirements. Simply passing around the requirements document for comments isn’t sufficient to reveal ambiguities. Suppose different reviewers interpret a requirement in different ways but it makes sense to each of them. That doesn’t reveal the ambiguity! Writing test cases against the requirements and building prototypes are other ways to discover ambiguities.

Gold Plating

Gold plating takes place when a developer adds new functionality that he believes “the users are just going to love.” Often, users don’t care about that functionality, and the time spent implementing it is wasted. Rather than simply inserting new features, developers and analysts should present the customers with creative ideas and alternatives for their consideration. Developers should strive for leanness and simplicity, not for going beyond what the customer requests without customer approval.

Customers sometimes request features or elaborate user interfaces that look cool but add little value to the product. Everything you build costs time and money, so you need to maximize the delivered value. To reduce the threat of gold plating, trace each bit of functionality back to its origin so that you know why it’s included.

Minimal Specification

Sometimes marketing staff or managers are tempted to create a limited specification, perhaps just a product concept sketched on a napkin. They expect the developers to flesh out the spec as the project progresses. This approach can work with a tightly integrated, agile team that’s building an application incrementally, on exploratory or research projects, or when the requirements truly are flexible. In other cases, though, it frustrates the developers (who might be operating under incorrect assumptions and with limited direction) and disappoints the customers (who don’t get the product they envisioned).

Overlooked User Classes

Most products have several groups of users who might use different subsets of features, have different frequencies of use, or have varying experience levels. If you don’t identify the important user classes for your product early on, some user needs won’t be met. After identifying all user classes, make sure that each has a voice, some person who will work with the business analyst to elicit the needs of a specific user class.

Inaccurate Planning

“Here’s my idea for a new product; when will you be done?” Don’t answer this question until you know more about the problem being discussed. Vague, poorly understood requirements lead to overly optimistic estimates, which come back to haunt us when the inevitable overruns occur. An estimator’s off-the- cuff guess sounds a lot like a commitment to the listener. The top contributors to poor software cost estimation are frequent requirements changes, missing requirements, insufficient communication with users, poor specification of requirements, and insufficient requirements analysis.

Benefits from a High-Quality Requirements Process

A great reward from effective requirements processes comes from reducing unnecessary rework during development and throughout the lengthy operational period. Many people mistakenly believe that time spent discussing requirements simply delays delivery by the same duration. A holistic cost-of-quality perspective, though, reveals the value of emphasizing early-stage quality practices. Sound requirements processes emphasize a collaborative approach to product development that involves multiple stakeholders in a partnership throughout the project. Collecting requirements lets the development team better understand its users or market.

Engaging users in the requirements-gathering process generates enthusiasm for the product and builds customer loyalty. By emphasizing user tasks instead of superficially attractive features, the team can avoid writing code that won’t ever be used. Customer involvement reduces the expectation gap between what the user needs and what the developer delivers. You’re going to get the customer feedback eventually. Try to get it early rather than late, perhaps with the help of prototypes that stimulate user feedback. This is far cheaper than correcting a lot of problems in beta testing or after release. Documented, unambiguous requirements greatly facilitate system testing, which in turn increases your chances of delivering high-quality products that satisfy all stakeholders.

No one can promise a specific return on investment from an improved requirements process. You can go through an analytical thought process to imagine how better requirements could help you, though. First, consider the cost of investing in a better process. This includes the cost of assessing your current practices, developing new procedures and document templates, training the team, buying books and tools, and perhaps using outside consultants.

Your greatest investment is the time your teams spend gathering, documenting, reviewing, and managing their requirements. Next, think about the possible benefits you might enjoy and how much time or money they could save you. You can’t quantify all the following benefits, but they’re real:

• Fewer requirements defects • Reduced development rework • Fewer unnecessary features • Lower enhancement costs • Faster development • Fewer miscommunications • Reduced scope creep • Reduced project chaos • Higher customer and team member satisfaction

Jama Software has partnered with Karl Wiegers to share licensed content from his books and articles on our web site via a series of blog posts, whitepapers and webinars.  Karl Wiegers is an independent consultant and not an employee of Jama.  He can be reached at http://www.processimpact.com.  Enjoy these free requirements management resources.

 

The CEO of a major corporation who was present when I described requirements traceability at a seminar asked, “Why wouldn’t you create a requirements traceability matrix for your strategic business systems?” That’s an excellent question. He clearly saw the value of having that kind of data available to the organization for each of its applications. If you agree with this executive’s viewpoint, you might be wondering how to incorporate requirements traceability into your systems development activities in an effective and efficient way.

Tracing requirements is a manually intensive task that requires organizational commitment and an effective process. Defining traceability links is not much work if you collect the information as development proceeds, but it’s tedious and expensive to do on a completed system. Keeping the link information current as the system undergoes development and maintenance takes discipline. If the traceability information becomes obsolete, you’ll probably never reconstruct it. Outdated traceability data wastes time by sending developers and maintainers down the wrong path, so it’s actually worse than having no data at all.

Requirements Traceability Procedure

If you’re serious about this effort, you need to explicitly make gathering and managing requirements traceability data the responsibility of certain individuals. Otherwise, it just won’t happen. Typically, a business analyst or a quality assurance engineer collects, stores, and reports on the traceability information. Consider following this sequence of steps when you begin to implement requirements traceability on a specific project:

  1. Select the link relationships you want to define from the possibilities shown in Figure 2 from the first article in this series on requirements traceability.
  2. Take another look at the second article in this series and choose the type of traceability matrix you want to use: the single matrix shown in Table 1 or several of the matrices illustrated in Table 2. Select a mechanism for storing the data—a table in a text document, a spreadsheet, or a commercial requirements management tool.
  3. Identify the parts of the product for which you want to maintain traceability information. Start with the critical core functions, the high-risk portions, or the portions that you expect to undergo the most maintenance and evolution over the product’s life.
  4. Modify your development procedures and checklists to remind developers to update the links after implementing a requirement or an approved change. The traceability data should be updated as soon as someone completes a task that creates or changes a link in the requirements chain.
  5. Define the tagging conventions you will use to uniquely identify all system elements so they can be linked together. If necessary, write scripts that will parse the system files to construct and update the traceability matrices. If you don’t have unique and persistent labels on requirements, design elements, and other system elements, there’s no way you can document the connections between them.
  6. Educate the team about the concepts and importance of requirements tracing, your objectives for this activity, where you will store the traceability data, and the techniques for defining the links—for example, using the tracing features of a requirements management tool.
  7. Identify the individuals who will supply each type of link information and the person who will coordinate the traceability activities and manage the data. Obtain commitments from all of them to do their part.
  8. As development proceeds, have each participant provide the requested traceability information as they complete small bodies of work. Stress the need to assemble the traceability data as they work, rather than attempting to reconstruct it at a major milestone or at the end of the project.
  9. Audit the traceability information periodically to make sure it is being kept current. If a requirement is reported as implemented and verified, yet its traceability data is incomplete or inaccurate, your traceability process isn’t working as you intend.

This procedure is described as though you were starting to collect traceability information at the outset of a new project. If you’re maintaining a legacy system, odds are that you have some traceability data available. There’s no time like the present to begin accumulating this useful information. The next time you have to add an enhancement or make a modification, write down what you discover about connections between code, tests, designs, and requirements. Build the recording of traceability data into your procedure for modifying an existing software component. This small amount of effort might make it easier the next time someone has to work on that same part of the system. You’ll never reconstruct a complete requirements traceability matrix, but you can grow a body of knowledge a bit at a time during the application’s life.

Is Requirements Traceability Feasible? Is it Necessary?

You might conclude that creating a requirements traceability matrix is more expensive than it’s worth or that it’s not feasible for your project. That’s fine: it’s your decision. But consider the following counter-example. A seminar attendee who worked at an aircraft manufacturer told me that the requirements specification for his team’s part of the company’s latest jetliner was a stack of paper six feet thick. They had a complete requirements traceability matrix. I’ve flown on that very model of airplane several times, and I was happy to hear that the developers had managed their requirements so carefully. Managing traceability on a huge product with many interrelated subsystems is a lot of work. This aircraft manufacturer knows it is essential; the Federal Aviation Administration agrees.

Not all companies build products that can have grave consequences if the software has problems. However, you should take requirements tracing seriously, especially for your business’s core information systems. You should decide to use any improved requirements engineering practice based on both the costs of applying the technique and the risks of not using it. As with all software processes, make an economic decision to invest your valuable time where you expect the greatest payback.

Check out Links in the Requirements Chain, Part 1

Check out Links in the Requirements Chain, Part 2

Jama Software has partnered with Karl Wiegers to share licensed content from his books and articles on our web site via a series of blog posts, whitepapers and webinars.  Karl Wiegers is an independent consultant and not an employee of Jama.  He can be reached at http://www.processimpact.com.  Enjoy these free requirements management resources.

 

The first part in this series of articles presented an overview of requirements traceability, identified the potential kinds of traceability links you could define among a project’s artifacts, and stated several motivations for tracing requirements. This article, adapted from my book Software Requirements, 2nd Edition, describes the requirements traceability matrix.

The Requirements Traceability Matrix

The most common way to represent the links between requirements and other system elements is in a requirements traceability matrix, also called a requirements trace matrix or a traceability table. Table 1 illustrates a portion of one such matrix. When I’ve set up such matrices in the past, I made a copy of the baselined SRS and deleted everything except the labels for the functional requirements. Then I set up a table formatted as in Table 1 with only the Functional Requirement column populated. As fellow team members and I worked on the project, we gradually filled in the blank cells in the matrix.

Table 1. One Kind of Requirements Traceability Matrix

Table 1 shows how each functional requirement is linked backward to a specific user requirement (represented in the form of use cases in this example), and forward to one or more design, code, and test elements. Design elements could be objects in analysis models such as data flow diagrams, tables in a relational data model, or object classes. Code references can be class methods, stored procedures, source code filenames, or procedures or functions within the source file. You can add more columns to extend the links to other work products, such as online help documentation. Including more traceability detail takes more work, but it also gives you the precise locations of the related software elements, which can save time during change impact analysis and system maintenance.

You should fill in the information as the work gets done, not as it gets planned. That is, enter “catalog.sort()” in the Code column of the first row in Table 1 only when the code has been written, has passed its unit tests, and has been integrated into the source code baseline for the product. This way a reader knows that populated cells in the requirements traceability matrix indicate completed work, not just good intentions.

When completing the matrix column for system test cases, note that listing the test cases for each requirement does not indicate that the software has passed that test. It simply indicates that tests have been written to verify the requirement at the appropriate time. Tracking testing status is a separate matter.

Nonfunctional requirements such as performance goals and quality attributes don’t always trace directly into code. A response-time requirement might dictate the use of certain hardware, algorithms, database structures, or architectural choices. A portability requirement could restrict the language features or coding conventions the programmers use, but it won’t necessarily turn into specific code segments that enable portability. Other quality attributes are indeed implemented in code, though. Integrity requirements for user authentication lead to derived functional requirements that are implemented through, say, passwords or biometrics functionality. In those cases, trace the corresponding functional requirements backward to their parent nonfunctional requirement and forward into downstream deliverables as usual. Figure 1 illustrates a possible traceability chain involving nonfunctional requirements.

Figure 1. Traceability chain for requirements dealing with application security.

Traceability links can define one-to-one, one-to-many, or many-to-many relationships between system elements. The format in Table 1 accommodates these cardinalities by letting you enter several items in each table cell. Here are some examples of the possible link cardinalities:

• One-to-one. One design element is implemented in one code module.

• One-to-many. One functional requirement is verified by multiple test cases.

• Many-to-many. Each use case leads to multiple functional requirements, and certain functional requirements are common to several use cases. Similarly, a shared or repeated design element might satisfy a number of functional requirements. Ideally, you will capture all these interconnections, but in practice many-to-many relationships can become complex and difficult to manage.

Another way to represent traceability information is through a set of matrices that define links between pairs of system elements, such as:

• One type of requirement to other requirements of that same type.

• One type of requirement to requirements of another type.

• One type of requirement to test cases.

You can use these matrices to define various relationships that are possible between pairs of requirements, such as “specifies/is specified by,” “depends on,” “is parent of,” and “constrains/is constrained by.”

Table 2 illustrates a two-way traceability matrix. Most cells in the matrix are empty. Each cell at the intersection of two linked components is marked to indicate the connection. You can use different symbols in the cells to explicitly indicate “traced-to” and “traced-from” or other relationships. Table 2 uses an arrow to indicate that a functional requirement is traced from a particular use case. These matrices are more amenable to automated tool support than is the single traceability table illustrated in Table 1.

Table 2. Requirements Traceability Matrix Showing Links Between Use Cases and Functional Requirements

Traceability links should be defined by whoever has the appropriate information available. Table 3 identifies some typical sources of knowledge about links between various types of source and target objects. Determine the roles and individuals who should supply each type of traceability information for your project. Expect some pushback from busy people whom the BA or project manager asks to provide this data. Those practitioners are entitled to an explanation of what requirements tracing is, why it adds value, and why they’re being asked to contribute to the process. Point out that the incremental cost of capturing traceability information at the time the work is done is small; it’s primarily a matter of habit and discipline.

Table 3. Likely Sources of Traceability Link Information

Tools for Requirements Tracing

It’s impossible to perform requirements tracing manually for any but very small applications. You can use a spreadsheet to maintain traceability data for up to a couple hundred requirements, but larger systems demand a more robust solution. Requirements tracing can’t be fully automated because the knowledge of the links originates in the development team members’ minds. However, once you’ve identified the links, tools can help you manage the vast quantity of traceability information.

There are numerous commercial requirements management tools that have strong requirements tracing capabilities. Two sources of information about such tools are http://www.incose.org/ProductsPubs/Products/rmsurvey.aspx and http://www.volere.co.uk/tools.htm. You can store requirements and other information in a tool’s database and define links between the various types of stored objects. Some tools let you differentiate “traced-to” and “traced-from” relationships, automatically defining the complementary links. That is, if you indicate that requirement R is traced to test case T, the tool will also show the symmetrical relationship in which T is traced from R.

Some tools automatically flag a link as suspect whenever the object on either end of the link is modified. The suspect links have a visual indicator such as a red question mark or a diagonal red line in a cell in the requirements traceability matrix. The suspect link indicators tell you to check, say, whether you need to change certain functional requirements to remain consistent with a modified use case. This feature helps ensure that you have accounted for the known ripple effects of a change.

Check out Links in the Requirements Chain, Part 1.

Check out Links in the Requirements Chain, Part 3.

The final article in this series will propose a process for incorporating requirements traceability practices into your project activities.

Jama Software has partnered with Karl Wiegers to share licensed content from his books and articles on our web site via a series of blog posts, whitepapers and webinars.  Karl Wiegers is an independent consultant and not an employee of Jama.  He can be reached at http://www.processimpact.com.  Enjoy these free requirements management resources.

 

Rather than expecting use cases to contain one hundred percent of the system’s functionality, I prefer to employ use cases to help the business analyst discover the functional requirements. That is, the use cases become a tool to reveal functionality rather than being an end requirements deliverable themselves. Users can review the use cases to validate whether a system that implemented the use cases would meet their needs. The BA can study each use case and derive the functional requirements the developer must implement to realize the use case in software. I like to store those functional requirements in a traditional SRS, although you could add them to the use case description if you prefer.

I’m often asked, “Which comes first: use cases or functional requirements?” The answer is use cases. Use cases represent requirements at a higher level of abstraction than do the detailed functional requirements. I like to focus initially on understanding the user’s goals so that we can see how they might use the product to achieve those goals. From that information, the BA can derive the necessary functionality that must be implemented so that the users can perform those use cases and achieve their goals. Conversely, if users present fragments of functionality during a requirements elicitation discussion, the BA should try to figure out which use case that functionality might with, if any.

Functional requirements—or hints about them—lurk in various parts of the use case. The remainder of this article describes a thought process a BA can go through to identify the less obvious functional requirements from the elements of a use case description.

Preconditions

Preconditions state conditions that must be true before the actor can perform the use case. The system must test whether each precondition is true. However, use case descriptions rarely state what the system should do if a precondition is not satisfied. The analyst needs to determine how best to handle these situations.

Suppose a precondition for one use case states, “The patron’s account must be set up for payroll deduction.” How does the system behave if the patron attempts to perform this use case but his account is not yet set up for payroll deduction? Should the system just notify the patron that he can’t proceed? Or should the system perhaps give the patron the opportunity to register for payroll deduction and then proceed with the use case? Someone has to answer these questions and the SRS is the place to provide the answers.

Postconditions

Postconditions describe outcomes that are true at the successful conclusion of the use case. The steps in the normal flow naturally lead to certain postconditions that indicate the user’s goal has been achieved. Other conditions, however, might not be visible to the user and therefore might not become a part of a user-centric use case description.

Consider an automated teller machine. After a cash withdrawal, the ATM software needs to update its record of the amount of cash remaining in the machine by subtracting the amount withdrawn. Perhaps if the cash remaining drops below a predetermined threshold the system is supposed to notify someone in the bank to reload the machine with additional money. I doubt any user will ever convey this information during a discussion of user requirements, yet the developer needs to know about this functionality.

How can you best communicate this knowledge to the developers and testers? There are two options. One is to leave the use case at the higher level of abstraction that represents the user’s view and have the requirements analyst derive the additional requirements through analysis. The BA can place those requirements in an SRS that is organized to best meet the developer’s needs. The second alternative is for the BA to include those additional details directly in the use case description. That behind-the-scenes information is not part of the user’s view of the system as a black box. Instead, you can think of that information as being white-box details about the internal workings of the use case that the analyst must convey to the developer.

Normal and Alternative Flows

The functionality needed to carry out the dialog between the actor and the system is usually straightforward. Simply reiterating these steps in the form of functional requirements doesn’t add knowledge, although it might help organize the information more usefully for the developer. The BA needs to look carefully at the normal flow and alternative flows to see if there’s any additional functionality that isn’t explicitly stated in the use case description. For example, under what conditions should the system offer the user the option to branch down an alternative flow path? Also, does the system need to do anything to reset itself so that it’s ready for the next transaction after the normal flow or an alternative flow is fully executed?

Exceptions

The BA needs to determine how the system could detect each exception and what it should do in each case. A recovery option might exist, such as asking the user to correct an erroneous data entry. If recovery isn’t possible, the system might need to restore itself to the state that existed prior to beginning the use case. The BA needs to identify the functionality associated with such recovery and restore activities and communicate that information to the developer.

Business Rules

Many use cases are influenced by business rules. The use case description should indicate which business rules pertain. It’s up to the BA to determine exactly what functionality the developer must implement to comply with each rule or to enforce it. These derived functional requirements should be recorded somewhere (I recommend documenting them in the SRS), rather than just expecting every developer to figure out the right way to comply with the pertinent business rules.

Special Requirements and Assumptions

The use case might assume that, for instance, the product’s connection to the Internet is working. But what if it’s not? The developer must implement some functionality to test for this error condition and handle it in an appropriate way.

In my experience, the process of having the BA examine a use case in this fashion to derive pertinent functional requirements adds considerable value to the requirements development process. There’s always more functionality hinted at in the use case than is obvious from simply reading it. Someone needs to discern this latent functionality. I would prefer to have an experienced BA do it rather than a developer.

Use Cases: A Pragmatic Approach

I recently spoke to a developer who said it was much more helpful to receive requirements information organized in a structured way from the BA than to have to figure out those details on his own. This developer preferred to rely on the BA’s greater experience with understanding the problem domain and deriving the pertinent functional requirements. Not only did this result in better requirements, but it also allowed the developer to focus his talents and energy where he added the most value, in designing and coding the software.

My philosophy of employing use cases as a tool to help me discover functional requirements means that I don’t feel a need to force every bit of functionality into a use case. It also gives me the option of writing use cases at whatever level of detail is appropriate. I might write some use cases in considerable detail to elaborate all their alternative flows, exceptions, and special requirements. I could leave other use cases at a high level, containing just enough information for me to deduce the pertinent functional requirements on my own. The functional requirements are the end result of requirements analysis, regardless of where you choose to store them or whether you even write them down at all. Developers don’t implement use cases: they implement specific fragments of functional behavior that allow users to accomplish valuable tasks with the software.

Deriving functional requirements from the use case always takes place on the journey from ideas to executable software. The question is simply a matter of who you want to have doing that derivation and when. If you deliver only use cases without all the functional detail to developers, each developer must derive the additional functionality on his own. It’s also unlikely that all developers will record the functional requirements they identify. This makes it hard for testers to know exactly what they need to test. It also increases the chance that someone will inadvertently fail to implement certain necessary functionality. If you’re outsourcing construction of the software, you can’t expect the vendor’s developers to accurately determine the unstated functionality from a use case description.

You will almost always have additional functional requirements that do not fit nicely into a particular use case. Earlier in this article, I mentioned the example of logging in to a system. Clearly, that functionality must be implemented, but I don’t consider it to be a use case. You might also have functional requirements that span multiple use cases. Consider the behavior the system should exhibit if a required Internet connection goes down. The Internet connection could fail while the user is executing any use case. Therefore, this error condition doesn’t constitute an exception flow associated with a specific use case. It needs to be detected and handled in multiple operations. The BA can place all the functional requirements that are not associated with or derived from a particular use case into the logically appropriate section of the SRS.

I have found use cases to be a highly valuable technique for exploring requirements on many types of projects. But I also value the structured SRS as an effective place to adequately document the functional requirements. Keep in mind that these documents are simply containers for different types of requirements information. You can just as readily store use cases, functional requirements, and other types of requirements information in the database of a requirements management tool or in other forms. Just don’t expect use cases to replace all your other strategies for discovering and documenting software requirements.

Read When Use Cases Aren’t Enough, Part 1.

Read When Use Cases Aren’t Enough, Part 2.

Jama Software has partnered with Karl Wiegers to share licensed content from his books and articles on our web site via a series of blog posts, whitepapers and webinars.  Karl Wiegers is an independent consultant and not an employee of Jama.  He can be reached at http://www.processimpact.com.  Enjoy these free requirements management resources.

I once read a book about use cases that stated, “To sum up, all functional requirements can be captured as use cases, and many of the nonfunctional requirements can be associated with use cases.” I agree with the second part of this sentence, but not with the first part. It is certainly true that use cases are a powerful technique for discovering the functional requirements for a system being developed. However, this statement suggests that use cases are the only tool needed for representing a software system’s functionality. In most cases, they aren’t.

Use Cases Don’t Replace Functional Requirements

This notion that all functional requirements can fit into a set of use cases and that use cases contain all the functional requirements for a system appears in many of the books and methodologies that deal with use cases. The thinking seems to be that the use cases are the functional requirements. If the BA writes good use cases, the developers are supposed to be able to build the system from that information, along with additional nonfunctional requirements information that’s included in a supplementary specification. Nonfunctional requirements, such as performance, usability, security, and availability goals, typically relate to a specific use case or even to a particular flow within a use case.

After querying the thousands of students I’ve taught in requirements seminars over the years, I have met just a single person who has found this pure use case approach to work! On the contrary, dozens of BAs have told me, “We gave our use cases to the developers and they got the general idea, but the use cases just didn’t contain enough information. The developers had to ask a lot of questions to get the additional requirements that weren’t in the use cases.” I suppose you could argue that they must not have been very good use cases. But when dozens of people report the same unsatisfactory experience when trying to apply a particular methodology, I question the methodology’s practicality.

There are three problems with adhering to this philosophy of use case purity. First, your use cases must contain all the functional detail that the analysts need to convey to the developers. That requires writing highly detailed use cases. The sample use cases in some books do include some complex examples. But elaborate use cases become hard to read, review, and understand.

The second problem with this approach is that it forces you to invent use cases to hold all the functional requirements because a use case is the only container you have available to describe system functionality. However, some system functionality does not fit appropriately into a use case. I have seen many new use case practitioners struggle to create inappropriate use cases to hold all the bits of functionality, to no useful end.

Logging in to an ATM or a Web site is an example that illustrates this problem. In their book Use Case Modeling (Addison Wesley, 2003) Kurt Bittner and Ian Spence provide this good definition of a use case:

Describes how an actor uses a system to achieve a goal and what the system does for the actor to achieve that goal. It tells the story of how the system and its actors collaborate to deliver something of value for at least one of the actors.

By this definition, logging in to a system is not a legitimate use case because it provides no value to the person who is logging in! No one logs in to a system and feels as though he accomplished something as a result. Logging in is a means to an end, a necessary step to being able to perform use cases that do provide value. Nevertheless, the functionality to permit login and everything associated with it (such as business rules or integrity requirements regarding passwords) must be defined somewhere. If you’re using only use cases as a container for functional requirements, you wind up being forced to invent artificial use cases—those that don’t provide user value—just to have a place to store certain chunks of functionality. This artificiality does not add value to the requirements development process.

Use Cases and an SRS Organize Information Differently

A third shortcoming of the use case–only philosophy is that use cases are organized in a way that makes good sense to users but not necessarily to developers. As Figure 1 illustrates, a use case consists of multiple small packages of information. A typical use case template contains sections for preconditions, postconditions, the normal flow of events, zero or more alternative flows (labeled with Alt. in Figure 1), zero or more exceptions (labeled with Ex.), possibly some business rules, and perhaps some additional special requirements.

Figure 1. Use case organization (left) differs from SRS organization (right).

These small packages are easy to understand and review, but they make it hard for the developer to see how the pieces fit together. As a developer myself, I find it more informative to see all the related requirements grouped together in a logical sequence. Suppose I read a functional requirement that implements a step in the normal flow. I want to see the requirements dealing with branch points into alternative flows and conditions that could trigger exceptions immediately following that one functional requirement. I’d like to see the requirements that handle each business rule in context, juxtaposed with the relevant system functionality. This is easier than having to figure out just what bits of the use case the business rule affects on my own.

As Figure 1 illustrates, the functional requirements that come from the various chunks of a use case can be sprinkled throughout a hierarchically organized SRS. Traceability analysis becomes important so that you can make sure every functional requirement associated with the use case traces back to a specific part of the use case. You also want to ensure that every piece of information in the use case leads to the necessary functionality in the SRS. In short, the way a use case is organized is different from the way many developers prefer to work.

It gets even more confusing if you’re employing use cases to describe the bulk of the functionality but have placed additional functional requirements that don’t relate to specific use cases into a supplemental specification. This approach forces the developer to get some information from the use case documentation and then to scour the supplemental specification for other relevant inputs. Before your analysts impose a particular requirements-packaging strategy on the developers, have these two groups work together to determine the most effective ways to communicate requirements information.

My preference is for the analyst to create an SRS as the ultimate deliverable for the developers and testers. This SRS should contain all the known functional and nonfunctional requirements, regardless of whether they came from use cases or other sources. Functional requirements that originated in use cases should be traced back to those use cases so that readers and analysts know where they came from.

In the final article of this three-part series, I’ll describe the thought process I go through when deriving functional requirements from the various elements of a use case.

Read the When Use Cases Aren’t Enough, Part 1.

Read the When Use Cases Aren’t Enough, Part 3.

Jama Software has partnered with Karl Wiegers to share licensed content from his books and articles on our web site via a series of blog posts, whitepapers and webinars.  Karl Wiegers is an independent consultant and not an employee of Jama.  He can be reached at http://www.processimpact.com.  Enjoy these free requirements management resources.

 

Use cases are recognized as a powerful technique for exploring user requirements. The great benefit they provide is to bring a user-centric and usage-centric perspective to requirements elicitation discussions. The business analyst employs use cases to understand what the user is trying to accomplish and how he envisions his interactions with the product leading to the intended user value. Putting the user at the center is much better than focusing on product features, menus, screens, and functions that characterize traditional requirements discussions. And the structure that use cases provide is far superior to the nearly worthless technique of asking users “What do you want?” or “What are your requirements?”

As with most new software development techniques, use cases have acquired a bit of a mystique, some misconceptions, overblown hype, and polarized camps of enthusiasts who will all try to teach you the One True Use Case Way. In this series of three articles (adapted from my book More about Software Requirements), I share my perspectives on when use cases work well, when they don’t, and what to do when use cases aren’t a sufficient solution to the requirements problem.

The Power of Use Cases

I’m a strong believer in the use case approach. Users can relate to and review use cases because the BA writes them from the user’s point of view, describing aspects of the user’s business. In my experience, once they get past the discomfort of trying a new technique, users readily accept the use case method as a way to explore requirements.

I’m often asked how to write requirements specifications so that users can read and understand them and also so that they contain all the detail that developers need. In many cases, one requirements representation won’t meet both of these objectives. Users can comprehend use cases, but they might balk at reviewing a more detailed mass of functional requirements. Use cases give developers an overall understanding of the system’s behavior that fragments of individual functionality cannot. However, developers usually need considerably more information than use cases provide so that they know just what to build. In many circumstances, the combination of employing use cases to represent user requirements and a software requirements specification to contain functional and nonfunctional requirements meets both sets of needs.

Project Type Limitations

My experience has shown that use cases are an effective technique for many, but not all, types of projects. Use cases focus on the user’s interactions with the system to achieve a valuable outcome. Therefore, use cases work well for interactive end-user applications, including Web sites. They’re also useful for kiosks and other types of devices with which users interact.

However, use cases are less valuable for projects involving data warehouses, batch processes, hardware devices with embedded control software, and computationally intensive applications. In these sorts of systems, the deep complexity doesn’t lie in the user–system interactions. It might be worthwhile to identify use cases for such a product, but use case analysis will fall short as a technique for defining all the system’s behavior.

As an illustration, I once worked on a computational program that modeled the behavior of a multi-stage photographic system. This software used a Monte Carlo statistical simulation to perform many complex calculations and it presented the results graphically to the user. The user-system dialog needed to set up each simulation run was quite simple. The complexity resided behind the scenes, in the computational algorithms used and the reporting of results. Use cases aren’t very helpful for eliciting the requirements for these aspects of a system.

Use cases also have limitations for systems that involve complex business rules to make decisions or perform calculations. Consider an airline flight reservation system, one of the classic examples used to illustrate use cases. Use cases are a fine technique for exploring the interactions between the traveler and the reservation system to describe the intended journey and the parameters associated with it. But when it comes to calculating the fare for a specific flight itinerary, a use case discussion won’t help. Such calculations are driven by the interaction of highly complex algorithms and rules, not by how the user imagines conversing with the system.

Nor are use cases the best technique for understanding certain real-time systems that involve both hardware and software components. Think about a complex highway intersection. It includes sensors in the road to detect cars, traffic signals, buttons pedestrians can press to cross the street, pedestrian walk signals, and so forth. Use cases don’t make much sense for specifying a system of this nature. Here are some possible use cases for a highway intersection:

  • A driver wants to go through the intersection.
  • A driver wants to turn left when coming from a particular direction.
  • A pedestrian wants to cross one of the streets.

These are use cases in the sense that they describe a goal a user is trying to achieve with the system, but they aren’t terribly useful in terms of illuminating the necessary system functionality. Exploring the interactions between these actors (drivers and pedestrians) and the intersection-control software system just scratches the surface of what’s happening with the intersection. The use cases don’t provide nearly enough information for the analyst to define the functionality for the intersection-control software.

Use cases aren’t particularly helpful for specifying the requirements for batch processes or time-triggered functions, either. My library’s information system automatically sends me an e-mail to remind me when an item I’ve borrowed is due back soon. This e-mail is generated by a scheduled process that checks the status of borrowed items overnight (the one I received today was sent at 1:06 AM) and sends out notifications. Some analysts regard “time” to be an actor so that they can structure this system behavior into a use case. I don’t find that helpful, though. If you know the system needs to perform a time-triggered function, just write the functional requirements for that function, instead of packaging it into a contrived use case.

Event-Response Tables

A more effective technique for identifying requirements for certain types of applications, such as real-time systems, is to consider the external events the system must detect. Depending on the state of the system at the time it detects a given event, the system produces a particular response. Event-response tables are a convenient way to collect this information.

Events could be signals received from sensors (signal events), time-based triggers such as scheduled program executions (temporal events), or user actions that cause the system to respond in some way (business events). In fact, the trigger that initiates a use case is sometimes termed a business event.

The highway intersection system described earlier has to deal with various events, including these:

  • A sensor detects a car approaching in one of the through lanes.
  • A sensor detects a car approaching in a left-turn lane.
  • A pedestrian presses a button to request to cross a street.
  • One of many timers counts down to zero.

Exactly what happens in response to an external event depends on the state of the system at the time it detects the event. The system might initiate a timer to prepare to change a light from green to amber and then to red. The system might activate a Walk sign for a pedestrian (if the sign currently reads Don’t Walk), or change it to a flashing Don’t Walk (if the sign currently says Walk), or change it to a solid Don’t Walk (if it’s currently flashing). The BA needs to write the functional requirements to specify both how to detect the events and the decision logic to use when combining events with states to produce system behaviors.

Table 1 presents a fragment of what an event-response table might look like for such a system. Each expected system behavior consists of a combination of event, system state, and response. State-transition diagrams and statechart diagrams are other ways to represent this information visually, but at a higher level of abstraction. Use cases just aren’t enormously helpful in this situation.

Table 1. Partial Event-Response Table for a Highway Intersection

Event

System State

Response
Road   sensor detects vehicle entering left-turn lane. Left-turn   signal is red. Cross-traffic signal is green. Start   green-to-amber countdown timer for cross-traffic signal.
Green-to-amber   countdown timer reaches zero. Cross-traffic   signal is green.
  1.   Turn cross-traffic signal amber.
  2.   Start amber-to-red countdown timer.
Amber-to-red   countdown timer reaches zero. Cross-traffic   signal is amber.
  1.   Turn cross-traffic signal red.
  2.   Wait 1 second.
  3.   Turn left-turn signal green.
  4.   Start left-turn-signal countdown timer.
Pedestrian   presses a specific walk-request button. Pedestrian   sign is solid Don’t Walk. Walk-request countdown timer is not activated. Start   walk-request countdown timer.
Pedestrian   presses walk-request button. Pedestrian   sign is solid Don’t Walk. Walk-request countdown timer is activated. Do   nothing.
Walk-request   countdown timer reaches zero plus the amber display time. Traffic   signal in walk direction is green. Change   all green traffic signals to amber.
Walk-request   countdown timer reaches zero. Traffic   signal in walk direction is amber.
  1.   Change all amber traffic signals to red.
  2.   Wait 1 second.
  3.   Set pedestrian sign to Walk.
  4.   Start don’t-walk countdown timer.

Defining the requirements for this complex system of interacting hardware and software components demands more than use cases. Most of the system’s complexity lies not in the user interactions but under the hood. An event-response approach will go much farther toward understanding the requirements for such a system.

Check out When Use Cases Aren’t Enough, Part 2.

Check out When Use Cases Aren’t Enough, Part 3.

Jama Software has partnered with Karl Wiegers to share licensed content from his books and articles on our web site via a series of blog posts, whitepapers and webinars.  Karl Wiegers is an independent consultant and not an employee of Jama.  He can be reached at http://www.processimpact.com.  Enjoy these free requirements management resources.

 

Software products are created for users, be they human beings, hardware devices, or other software systems. A user is a stakeholder who will interact with a completed system either directly (that is, hands on) or indirectly (for example, using reports from the system but not generating those reports personally). Users can be grouped into user classes, communities of users who have similar characteristics and similar requirements for a system.

Discussions of use cases always involve the concept of actors. An actor is an entity outside the system boundary that interacts with the system for the purpose of completing an event, such as execution of a use case. Actors are related to—but are not precisely the same as—user classes. This distinction between user classes and actors is subtle. It doesn’t help that the books on use cases employ somewhat different terminology. Here are the key points:

  • User classes represent groups of actual people or non-human users. A human user is a member of one or more user classes. You need to identify your product’s user classes so you know which people to talk with about requirements. You also need to understand which user classes are “favored” over others. Satisfying the needs of a favored user class is more important from a business perspective than meeting the needs of other groups of users. This distinction helps when making priority decisions and resolving requirement conflicts.
  • An actor is an abstraction, a role performed by a member of a specific user class when he interacts with a product at a specific time. When you are talking with user class representatives, have them identify the various roles that members of each class can perform from time to time. If those user roles involve interacting with the system through a use case, the roles represent actor names. Consider developing personas, descriptions of representative actors who can execute certain use cases.

I like to imagine the members of each user class as having a stack of hats available, each of which is labeled with a particular actor or role name. Whenever a user needs to perform a specific use case with the system, he puts on the hat labeled with the name of the actor who initiates that use case. The system behaves as though it’s interacting with that actor, regardless of what user class that individual user belongs to.

Figure 1 illustrates the relationship between actors and user classes for a bank. Bank Customers constitute one class of users of banking services. A particular Bank Customer might perform various functions from time to time with the bank’s systems, perhaps as an indirect user working through a bank employee. When performing those functions, the Bank Customer is assuming the role of a particular actor. When he makes a cash withdrawal from an automated teller machine, the customer is performing the role of an Account Owner. This is more specific than calling him a generic Bank Customer. As far as the ATM is concerned, it’s performing a service for an Account Owner.

Figure 1. A member of one user class could take on multiple actor roles.

On another occasion, that same person might walk into the bank and apply for a loan. At that time, he’s wearing the hat of a Loan Applicant actor, not an Account Owner. The system the customer interacts with at that time thinks of the user as being a Loan Applicant. In a third situation, a bank customer might deposit a check into an account he doesn’t own, perhaps on behalf of his spouse or a business colleague. In that case, the customer is filling the role of the Depositor actor. Note how many actor names end in -er or -or, which indicates that the actor is a performer attempting to accomplish a particular objective.

There could also be a many-to-one relationship between user classes and actors, as Figure 2 illustrates. When I worked on a project called the Chemical Tracking System at one company, we had several important user classes: chemists, chemical technicians, members of the chemical stockroom staff, and laboratory managers. Each of these groups had largely different sets of requirements, but there was some overlap. For example, members of all these user classes might have to place requests for chemicals periodically. Now, no one at this company had a job title of “chemical requester.” The Chemical Requester actor is an abstraction that represents anybody who needs to request a chemical and is authorized to do so. The system doesn’t care whether the person requesting a chemical works as a chemist, a lab manager, or something else. All the system knows is that a Chemical Requester actor is executing certain use cases associated with chemical request activities.

Figure 2. Members of multiple user classes could all perform as the same actor.

Actors appear in use case diagrams drawn according to the convention of the Unified Modeling Language. Figure 3 shows a portion of a use case diagram for the Chemical Tracking System. The box represents the system boundary. Each oval inside the box represents a single use case, something a user would need to accomplish with the help of the system. The stick figures outside the box represent actors. The stick figure notation is a standard convention that’s used whether the actor is a human being or an inanimate entity.

Figure 3. Use case diagrams show primary and secondary actors for specific use cases.

An arrow drawn from an actor to a use case indicates that the actor can initiate the corresponding use case; this is called the primary actor for that use case. The Chemical Requester actor can initiate the use cases Request a Chemical, Receive Chemical, Check Order Status, and so forth. An arrow directed from a use case to an actor indicates a secondary actor. Secondary actors participate in the completion of a use case, but they don’t derive the benefit from the use case; the primary actor gets the benefit. The Training Database and Buyer actors are secondary actors with respect to the Request a Chemical use case. The Chemical Tracking System might have to rely on the Training Database to see whether a user is properly trained in how to handle a dangerous chemical. And, if someone submits a request for a chemical that needs to be purchased from a vendor, the system will route that request to a Buyer for handling. Note that actors are primary or secondary with respect to a specific use case, not with respect to the overall system.

As you begin your requirements exploration, be sure to identify your user classes so that you know who you’ll need to talk to in order to discover user requirements. Key representatives of user classes (product champions) can work with the business analyst during elicitation. The product champions identify the use cases that represent tasks or goals that members of their user class will need to accomplish with the system’s help.

As you explore each use case, think of an appropriate name to describe the actor who will initiate that use case. Try to select a name that reflects what the user is attempting to accomplish, such as Chemical Requester, Buyer, or Loan Applicant. Consider whether members of other user classes might also have occasion to perform that same use case—that is, whether they might have occasion to function in that same actor role. The analyst should consult representatives of those user classes to see if their stated needs enrich his understanding of the use case, perhaps by identifying additional alternative flows.

Consider developing catalogs that describe your common user classes and actors so that you can reuse these definitions in a consistent fashion across multiple projects. Any opportunities for requirements reuse will reduce errors, save time, and help you build a more cohesive set of integrated products.

Jama Software has partnered with Karl Wiegers to share licensed content from his books and articles on our web site via a series of blog posts, whitepapers and webinars.  Karl Wiegers is an independent consultant and not an employee of Jama.  He can be reached at http://www.processimpact.com.  Enjoy these free requirements management resources.

 

Here are some additional recommendations about how to make peer reviews of your requirements documents as effective as possible.

Don’t Overwhelm the Reviewers

Many BAs wait until their requirements specification is complete before they present it to some reviewers. Busy developers, testers, project managers, and users have difficulty finding the time to scrutinize a large document on short notice. It’s far more effective to review an evolving document incrementally. Give reviewers just a few pages at a time, preferably soon after an elicitation activity. Nearly anyone should be able to find thirty minutes to review a small quantity of information once in a while.

Incremental, informal reviews will uncover a lot of problems. Expect to make multiple review passes through the requirements over time. Each review cycle will reveal errors that the reviewers didn’t spot the first time. As the requirements continue to change and grow, people might need to revisit portions of the requirements documentation that they examined in an earlier draft.

You don’t need to hold a meeting for each peer review. Sometimes it works fine just to ask one or a few reviewers to look something over and tell you what they see. Combine these sorts of informal individual reviews, which I call peer deskchecks, with formal inspections of documents that are nearly done.

Build a Collaborative Partnership with Project Stakeholders

Explain to users why their input is so critical to ensuring the quality of the requirements and how it contributes to the quality of the ultimate software product. Make them understand that their review effort is a vital contribution, not an idle exercise. Begin forging this collaboration early in the project so these participants realize they’re valued members of the team.

On many projects, my software development teams at Kodak identified product champions, key customer representatives who worked closely with the business analysts. We negotiated the exact responsibilities with each product champion. But one responsibility was not optional: to review requirements specifications and evaluate prototypes. Without user review, we couldn’t tell whether we’d accurately captured the voice of the customer. We were pleased that all of our product champions accepted this responsibility. They provided great value through their reviews.

Invite the Right Reviewers

Determine early in the project what perspectives you need represented in your requirements reviews and who can provide these perspectives. Figure 1 illustrates the essential points of view a requirements review should take into account. Particularly consider getting the participation of the following:

• Customers who provided requirements input.

• Developers who will have to design and implement the requirements.

• Testers who will have to verify that the requirements were properly implemented.

Work products must be reviewed in a context, not in isolation. The reviewers must ascertain whether the work product meets its own specification. The top-level requirements documentation has no specification or reference document, so you need customers or others who provided requirements input to review the deliverable. Also, you might invite another BA to participate who’s adroit at spotting poorly written or missing requirements. The downstream “victims” of the requirements specification can check to see whether it will satisfy their needs. And if your product connects in some way to any other products, have representatives of those other components make sure the pieces will fit together properly.

Rather than having all these different reviewers just read through the document, consider using perspective-based reading, in which each reviewer examines the deliverable from the point of view of a specific document consumer. For example, a user seeks to determine whether the documented requirements would in fact let him achieve his business objectives. A developer checks to see whether the document contains the information he needs to design and implement a solution. A tester considers whether the requirements are precise and detailed enough to be verifiable. These different points of view will reveal different types of problems.

Have Reviewers Examine Appropriate Deliverables

It might not be reasonable to expect all your user representatives to effectively review a detailed software requirements specification. They should certainly understand use cases, though, as use cases ought to be written from the user’s point of view. Make sure your reviewers can comprehend the requirements documents and diagrams well enough to validate them. If the requirements documents are too technical for the reviewers to follow, you’re wasting their time.

Design for Reviewability

Present the information in a specification in forms that make it easy for reviewers to understand it and to examine it for problems. There are many ways to communicate besides natural language text. If your eyes glaze over when reading a long list of textual requirements, maybe a diagram or a table would be an effective alternative. Remember that a requirements specification is a communication tool. If your requirements deliverables don’t speak to their intended audiences, the deliverables need further work.

Inspect All Requirements Deliverables

Informal reviews certainly are helpful, but more systematic inspections will find more defects. Inspections and other group reviews also are a way to force the issue of getting reviewers to actually look at the work product. Inspections are a powerful technique for spotting ambiguous requirements. During an inspection, one inspector (not the author) serves as the reader. The reader presents his interpretation of each requirement to the other inspectors. If his interpretation doesn’t match their own understanding, perhaps the team has detected an ambiguity, a statement that can be interpreted in more than one way. Individual informal reviews often overlook ambiguities because an ambiguous requirement can make sense to each reader, even if it means something different to each of them.

Emphasize Finding Major Errors

The greatest leverage from a review comes from finding major errors of commission and omission. These are the defects that can help you avoid extensive—and expensive—rework much later in the project. Ambiguous and erroneous requirements send developers and testers in the wrong direction. Missing requirements are among the hardest errors to detect. They’re invisible, so inspectors don’t see them during their individual preparation. Because they don’t exist, the inspection reader won’t describe them.

Fixing typographical and grammatical errors is useful because any changes that enhance effective communication are valuable. However, this should be done before sending out the document out for broad review, perhaps by having a single skilled editor go through it initially. Otherwise, reviewers can trip on these superficial errors and fail to spot the big defects that lie underneath. When I see an issues log from a review that contains mostly cosmetic and spelling mistakes, I worry that perhaps the reviewers overlooked major problems.

No business analyst can get the requirements right on his own. Get a little help from your friends to make sure that what you’ve written will satisfy customer needs and will let the rest of the development team do a first-class job.

Check out Peer Reviews: Two Eyes Aren’t Enough, Part 1.

Jama Software has partnered with Karl Wiegers to share licensed content from his books and articles on our web site via a series of blog posts, whitepapers and webinars.  Karl Wiegers is an independent consultant and not an employee of Jama.  He can be reached at http://www.processimpact.com.  Enjoy these free requirements management resources.

 

In my view, the most powerful quality practice available to the software industry today is inspection of requirements documentation. A peer review is an activity in which someone other than the author of a work product examines that product to find defects and improvement opportunities. An inspection is a type of formal, rigorous team peer review that can discover more subtle problems than individual reviewers might spot on their own. Removing errors in the requirements saves many times the cost of the inspection because of the rapidly escalating cost of remedying defects that are found later in the project.

Unfortunately, inspections and other peer reviews of requirements documents often aren’t held when intended, and those that are performed don’t always go well. Reviewers take only a superficial look (if they look at all), and they miss many of the major defects that lurk in the specification. Conducting an ineffective review can give the team unjustified confidence in the work product’s quality.

This pair of articles, adapted from my book More about Software Requirements, presents several ways to make your requirements reviews more effective and to encourage prospective reviewers to participate in them. For an in-depth exploration of different peer review approaches and how to make them work for you, see my book Peer Reviews in Software: A Practical Guide (Addison-Wesley, 2002).

Note that, although I refer to requirements documents in these articles, the same principles also apply whether you’re storing your requirements in a spreadsheet, a database, a requirements management tool, or on note cards. No matter what their form, you really ought to have multiple pairs of eyes examine your project’s requirements for problems.

Educate the Reviewers

Suppose someone hands you a document and asks for your input. Your instinctive approach probably is to begin reading at the top of page one and see whether any problems jump out at you as you go. Maybe you’re not too sure what to look for. As you continue reading, you begin to get tired and bored. Your own work backlog tugs at your conscience. So you flip through the rest of the pages, tell the author about the minor issues you found, and move on with your life. There’s a better way.

Don’t expect that reviewers will automatically know what to do. If you’re a business analyst who’s relying on input from others to validate and verify your requirements, you need to educate your reviewers. Ideally, you can get them to take some training on how to perform peer reviews, such as my eLearning course called “Software Inspections and Peer Reviews” (http://www.processimpact.com/elearning.shtml#sipr). If not, at least tell them about the purpose of reviews, the various sorts of review approaches, and what you expect of the reviewers. This is particularly important if you plan to hold inspections, which involve a more structured process than do the more familiar informal reviews.

Interact Respectfully

Peer reviews are at least as much a social interaction as they are a technical practice. I believe that asking someone to tell you about mistakes in your work is a learned behavior, not an instinctive behavior. Authors need to learn how to request and accept constructive input about mistakes they’ve made. If you’re holding inspections or team reviews that involve a meeting, make sure the participants understand how to collaborate effectively and constructively. Many organizations hold ineffective reviews because participants are uncomfortable and they aren’t sure how to behave in a review meeting.

One state government agency that hired me as a consultant told me that their review participants refer to the review as “going into the shark tank”—not an appealing prospect. If you’ve been burned by a caustic review in the past, you’ll be reluctant to participate in such a stressful and ego-busting experience again. Therefore, it’s important to make reviews be constructive experiences in which all participants feel that they’re contributing to improving the team’s collective work products.

People need to be considerate when they provide feedback to the author of the work product being reviewed. I like to simply make observations about the product, rather than telling the author he did something wrong. If you’re the author, you might react differently if a reviewer accusingly says, “You forgot to fill in section 3.4 of the SRS template,” instead of simply commenting: “I didn’t see anything entered in section 3.4 here” or “Section 3.4 seems to be missing.” Be thoughtful about how you phrase your comments. Perhaps you’re a reviewer today, but you might be the author the next time.

Focus on Specific Problems

Tell the reviewers what kind of input you’re seeking in each situation so they can focus their attention on giving you useful feedback. Give them tips on how to study and analyze a requirements specification. For example, you might invite certain reviewers to start reading at some point other than the beginning of the document. After all, developers won’t read the entire document sequentially during construction. This is a way to get fresh eyes looking at various sections, rather than having all of the reviewers peter out partway through the document and miss a lot of errors in the latter pages. Some people suggest reading the document from back to front, section by section, to see whether the questions they come up with are all answered earlier in the document.

Give the reviewers a checklist of typical requirements errors so they can focus their examination on those points. You can find checklists for reviewing software requirements specifications and use case documents at http://www.processimpact.com/pr_goodies.shtml. You might suggest that the reviewers make multiple passes through the document, perhaps during separate review cycles of a growing document. They can look for different types of problems from the checklist during each pass. Alternatively, ask different reviewers to use separate parts of the checklist to broaden the review coverage. Eventually requirements reviewers will internalize the review checklists and know what sorts of problems to look for.

In part two of this article I’ll share some additional tips for making your requirements reviews as effective as possible.

Check out Peer Reviews: Two Eyes Aren’t Enough, Part 2.

Jama Software has partnered with Karl Wiegers to share licensed content from his books and articles on our web site via a series of blog posts, whitepapers and webinars.  Karl Wiegers is an independent consultant and not an employee of Jama.  He can be reached at http://www.processimpact.com.  Enjoy these free requirements management resources.