Author: Karl Wiegers

Karl Wiegers is Principal Consultant with Process Impact, a software development consulting and training company in Portland, Oregon. He has a PhD in organic chemistry. Karl is the author of 14 books, including Software Requirements Essentials, Software Requirements, More About Software Requirements, Successful Business Analysis Consulting, Software Development Pearls, The Thoughtless Design of Everyday Things, and a forensic mystery novel titled The Reconstruction. Karl also has written many articles on software development, design, project management, chemistry, military history, and consulting, as well as 18 songs. You can reach him at ProcessImpact.com or KarlWiegers.com.

Cosmic Truths about Software Requirements, Part 2

Written by Karl Wiegers on May 14, 2013. Posted in Articles. 1 Comment on Cosmic Truths about Software Requirements, Part 2

The first article in this series presented three “cosmic truths,” realities about requirements that I’ve discovered to apply to virtually all software projects. This article continues with three more such insights, focusing on requirements and the project stakeholders.

Cosmic Truth #4: The interests of all the project stakeholders intersect in the requirements process.

Consultant Tim Lister once defined project success as “meeting the set of all requirements and constraints held as expectations by key stakeholders.” A stakeholder is an individual or group who is actively involved in the project, who is affected by the project, or who can influence its outcome. Figure 1 identifies some typical software project stakeholders. Certain stakeholders are internal to the project team, such as the project manager, business analysts, developers, and testers. Other stakeholders are external, including customers who select, specify, or fund products; users who employ the systems; compliance certifiers; auditors; and marketing, sales, and support groups. The business analyst performs a central communication role, being responsible for interacting with all these stakeholders. Further, the BA is responsible for seeing that the system being defined will be fit for use by all customers, perhaps working with a system architect to achieve this goal.

Identify your key stakeholder groups at the beginning of the project. Then determine which individuals will best represent the interests of each group. You can count on stakeholders having conflicting interests that must be reconciled. They can’t all have veto power over each other. You need to identify early on the decision makers who will resolve these conflicts, and these decision makers must determine what their decision-making process will be. As my friend Chris, a seasoned project manager, points out, “I have found that there is usually one primary decision maker on a project, oftentimes the key sponsor within the organization. I don’t rest until I have identified that person, and then I make sure he is always aware of the project’s progress.”

Cosmic Truth #5: Customer involvement is the most critical contributor to software quality.

Various studies have confirmed that inadequate customer involvement is a leading cause of the failure of software projects. Customers often claim they can’t spend time working on requirements. However, customers who aren’t happy because the delivered product missed the mark always find plenty of time to point out the problems. The development team is going to get the customer input it needs eventually. It’s a lot cheaper—and a lot less painful—to get that input early on, rather than after the project ostensibly is done.

Customer involvement requires more than holding a workshop or two early in the project. Ongoing engagement by suitably empowered and enthusiastic customer representatives is a critical success factor for software development. Following are some good practices for engaging customers in requirements development (see my book Software Requirements for more information about these practices):
Identify user classes. Customers are a subset of stakeholders, and users are a subset of customers. You can further subdivide your user community into multiple user classes that have largely distinct needs.

Unrepresented user classes are likely to be disappointed with the project outcome.

Select product champions. You need to determine who will serve as the literal voice of the customer for each user class. I call these people product champions. Ideally, product champions are actual users who represent their user-class peers. In some cases, though, you might have limited access to actual users, so you need to employ surrogates to speak for certain user classes to the best of their ability. Such surrogates might be subject matter experts or marketing personnel. When developers are forced into the position of trying to identify user needs, they often don’t do a great job.

Build prototypes. Prototypes provide opportunities for user representatives to interact with a simulation or portion of the ultimate system. Prototypes are far more tangible than written requirements specifications and easier for users to relate to. However, prototypes aren’t a substitute for documenting the detailed requirements. You also have to watch out for the risk that users who evaluate prototypes will conclude that the system is almost done and press the development team to release the prototype as a delivered product. This is usually a disaster.

Agree on customer rights and responsibilities. People who must work together rarely discuss the nature of their collaboration. The BA should negotiate with the customer representatives early in the project to agree on the responsibilities each party has with respect to the requirements process. An agreed-upon collaboration strategy is a strong contributor to the participants’ mutual success.

Cosmic Truth #6: The customer is not always right, but the customer always has a point.

It’s popular in some circles to do whatever any customer demands, claiming “The customer is always right.” Of course, the customer is not always right! We all know this. Sometimes customers are in a bad mood, uninformed, or unreasonable. If you receive conflicting input from multiple customers, which one of those customers is “always right”? It’s a silly philosophy.

The customer might not always be right, but the BA needs to understand and respect whatever point each customer is trying to make through his request for certain product features or attributes. The BA must be alert for situations in which the customer could be in the wrong. Rather than simply promising anything a customer requests, strive to understand the rationale behind the customer’s thinking and negotiate an acceptable outcome. Following are some examples of situations in which a customer might not be right:

Presenting solutions in the guise of requirements.
Failing to prioritize requirements or expecting the loudest voice to get top priority.
Not communicating business rules and other constraints, or trying to get around them.
Expecting a new software system to drive business process changes.
Not supplying appropriate representative users to participate in requirements elicitation.
Failing to make timely decisions when a BA or developer needs an issue resolved.
Not accepting the need for tradeoffs in both functional and nonfunctional requirements.
Demanding impossible commitments.
Not accepting the cost of change.

The final article in this series will present four additional cosmic truths dealing with requirements specifications.

Don’t forget to leave your comments below.

Cosmic Truths about Software Requirements, Part 1

Written by Karl Wiegers on April 16, 2013. Posted in Articles.

As every consultant knows, the correct answer to nearly any question regarding software is “It depends.” I realize that’s not a very satisfying answer, but this isn’t just a consultant’s cop-out—it’s true. The best advice for how to proceed in a given situation depends on the nature of the project, its constraints, the culture of the organization and team, the business environment, and other factors.

That said, having worked with many organizations, I’ve made some observations about software requirements that really do seem to be universally applicable. In this series of three articles (adapted from my book More about Software Requirements) I present some of these “cosmic truths” and their implications for the practicing business analyst.

Cosmic Truth #1: If you don’t get the requirements right, it doesn’t matter how well you execute the rest of the project.

Requirements serve as the foundation for all the project work that follows. I don’t mean the initial software requirements specification you come up with early in the project, but rather the full set of requirements knowledge that is developed incrementally during the course of the project.

The purpose of a software development project is to build a product that provides value to a particular set of customers. Requirements development attempts to determine the mix of product capabilities and characteristics that will best deliver this customer value. This understanding evolves over time as customers provide feedback on the early work and refine their expectations and needs. If this set of expectations isn’t adequately explored and crafted into a set of product features and attributes, the chance of satisfying customer needs is slim.

Requirements validation is one of the vital subcomponents of requirements development, along with elicitation, analysis, and specification. Validation involves demonstrating that the specified requirements will meet customer needs. One useful technique for validating requirements is to work with suitable customer representatives to develop user acceptance criteria. These criteria define how customers determine whether they’re willing to pay for the product or to begin using it to do their work. User acceptance criteria typically stipulate that the product allows the users to properly perform their most significant tasks, handles the common error conditions, and offers an acceptable level of quality. User acceptance criteria aren’t a substitute for thorough system testing. They do, however, provide a necessary perspective to determine whether the requirements are indeed right.

Cosmic Truth #2: Requirements development is a discovery and invention process, not just a collection process.

People often talk about “gathering requirements.” This phrase suggests that the requirements are just lying around waiting to be picked like flowers or to be sucked out of the users’ brains by the BA. I prefer the term requirements elicitation to requirements gathering. Elicitation includes some discovery and some invention, as well as recording those bits of requirements information that customer representatives offer to the BA. Elicitation demands iteration. The participants in an elicitation discussion won’t think of everything they’ll need up front, and their thinking will change as the project continues. Requirements development is an exploratory activity.

A business analyst is not simply a scribe who records what customers say. The BA is an investigator who asks questions that stimulate the customers’ thinking, seeking to uncover hidden information and generate new ideas. It’s fine for a BA to propose requirements that might meet customer needs, provided the customers agree that those requirements add value before they go into the product. A BA might ask customers, “Would it be helpful if the system could do ?” The customer might reply, “No, that wouldn’t do much for us.” Alternatively, the customer might reply, “You could do that? Wow, that would be great! We didn’t even think to ask for that feature, but it would save our users a lot of time.”

This creativity is part of the value the BA adds to the requirements conversation. Just be careful that BAs and developers don’t attempt to define a product from the bottom up through suggested product features. It’s better to base the requirements on an understanding of stakeholder goals and a broad definition of success.

Cosmic Truth #3: Change happens.

It’s inevitable that requirements will change. Business needs evolve, new users or markets are identified, business rules and government regulations are updated, and operating environments change over time. In addition, the business need becomes clearer as the key stakeholders become better educated about what their true needs are.

The objective of a change control process is not to inhibit change. Rather, the objective is to manage change to ensure that the project incorporates the right changes for the right reasons. You need to anticipate and accommodate changes to produce the minimum disruption and cost to the project and its stakeholders. However, excessive churning of the requirements after they’ve been agreed upon suggests that elicitation was incomplete or ineffective—or that agreement was premature.

To help make change happen, establish a change control process. You can download an example of such a process from my website . When I helped to implement a change control process in an Internet development group at Kodak, the team members properly viewed it as a useful structure, not as a barrier. The group found this process invaluable for dealing with its mammoth backlog of change requests.

Every project team also needs to determine who will evaluate requested changes and decide to approve or reject them. This group is typically called the change control board, or CCB. A CCB should write a charter that defines its composition, scope of authority, operating procedures and decision-making process. A template for such a charter also is available on my website .

Nearly every software project becomes larger than originally anticipated, so expect your requirements to grow over time. According to consultant Capers Jones, requirements growth typically averages one to three percent per month. This can have a significant impact on a long-term project. To accommodate some expected growth, build contingency buffers—also known as management reserve—into your project schedules.

These buffers will keep your commitments from being thrown into disarray with the first change that comes along.

I once spoke with a manager on a five-year project regarding requirements growth. I pointed out that, at an average growth rate of two percent per month, his project was likely to be more than double the originally estimated size by the end of the planned sixty-month schedule. The manager agreed that this was plausible. When I asked if his plans anticipated this growth potential, he gave the answer I expected: No. I was highly skeptical that this project will be completed without enormous cost and schedule overruns.

When you know that requirements are uncertain and likely to change, use an incremental or iterative development life cycle. Don’t attempt to get all the requirements “right” up front and freeze them. Instead, specify and baseline the first set of requirements based on what is known at the time. A baseline is a statement about the state of the requirements at a specific point in time: “We believe that these requirements will meet a defined set of customer needs and are a suitable foundation for proceeding with design and construction.” Then, implement that fraction of the product, get some customer feedback, and move on the next slice of functionality. This is the intent behind agile development methodologies, the spiral model, iterative prototyping, evolutionary delivery, and other incremental approaches to software development.

Finally, recognize that change always has a price. It is never free. Even the act of considering a proposed change and then rejecting it consumes effort. Software people need to educate their project stakeholders so they understand that, sure, we can make that change you just requested, and here’s what it’s going to cost. Then the stakeholders can make appropriate business decisions about which desired changes should be incorporated and at what time.

Speaking of which, the next article in this series will present several cosmic truths about requirements and project stakeholders

Don’t forget to leave your comments below.

Elements of Requirements Style, Part 3

Written by Karl Wiegers on December 18, 2012. Posted in Articles. 2 Comments on Elements of Requirements Style, Part 3

One of the most common types of requirements problem is missing information. Either entire requirements could be absent—which are hard to spot, being invisible—or individual requirements are missing information that help make them fully comprehensible. In this article, the third in a series of four, I’ll present some examples of both kinds of problems, along with some recommended solutions.

Omissions

When requirements lack important bits of information, it’s hard for all readers to interpret them in the same way unless they make precisely the same assumptions. For instance, a functional requirement might describe a behavior without identifying the triggering cause that leads to that behavior:

The system shall generate an error report and forward it to the user.

This requirement doesn’t identify the stimulus that leads the system to produce the error report. Another common mistake involves missing descriptions of how possible exceptions should be handled. In the previous example, what should happen if no errors occur during the processing being described? It’s unspecified, thereby leaving it up to the developer to decide what to do. Options include:

Do nothing (an assumed default perhaps).
Present a “Congratulations! No errors found.” message but do not generate a report.
Generate an empty report and forward it to the user.
Generate a report stating that no errors were found and forward it to the user.

Perhaps we add the following requirement to address the case in which no errors are encountered:

If parsing is successful, the system shall not generate an error report.

This is another description of the system doing nothing, though, as I discussed under “Negative Requirements” in a earlier article in this series. It would be better to state what the system will do if no error is encountered, even if it is to simply continue the processing.

Another kind of incompleteness occurs when requirements describe system behaviors that involve some type of symmetry. Suppose you’re specifying the functional requirements for a bookmark feature in a Web browser. You might say:

The system shall display the user’s defined bookmarks in a collapsible hierarchical tree structure.

So, the user can collapse the bookmark tree, but what if he wants to expand it again? It’s easy to overlook that sort of symmetrical or reverse operation. To remedy this, either you could add a second requirement stating that the tree can be expanded, or you could alter this requirement to say “…in a collapsible and expandable hierarchical tree structure.”

If you omit the reverse operation, the customer and the BA might assume that the missing portion of the symmetrical requirement is implied. If you request an undo capability, of course you want a redo capability as well, right? But implicit requirements make me nervous. They involve too many assumptions about the knowledge and thought processes that other stakeholders must have to ensure that we all get what we expect in the final product. I know of a organization that developed its own tool for editing and storing source code in a database, with no written requirements. Unfortunately, they forgot to include the ability to print the contents of the database. The team members no doubt assumed that a printing function would be included so didn’t even think to mention it. They didn’t mention it, and they didn’t get it.

Boundaries

Boundary values in numerical ranges provide additional opportunities for creating ambiguity, as well as being places to look for missing requirements. Suppose you’re writing software for a point-of-sale system and you need to comply with a business rule that states, “Only supervisors may issue cash refunds greater than $50.” An analyst might derive several functional requirements from that business rule, such as the following:

If the amount of the cash refund is less than $50, the system shall open the cash register drawer.
If the amount of the cash refund is more than $50 and the user is a supervisor, the system shall open the cash register drawer. If the user is not a supervisor, the system shall display a message: “Call a supervisor for this transaction.”

But what if the amount of the cash refund is exactly $50? Is this a third, unspecified case? Or is it one of the two cases already described? If so, which one? Such ambiguity forces the developer either to make his best guess or to track down someone who can answer the question definitively. This is an example of the BA generating an inconsistency between a higher-level piece of information—the business rule—and the functional requirements derived from it.

You can resolve boundary ambiguities in one of two ways. The previous requirement #1 could be rewritten as, “If the amount of the cash refund is less than or equal to $50, the system shall open the cash register drawer.” This preserves the original intent of the business rule and eliminates the ambiguity.

Alternatively, you could use the words inclusive and exclusive to explicitly indicate whether the endpoints of a numerical range are considered to lie within the range or outside the range. To illustrate with a different example, you might say, “The system shall calculate a 20% discount on orders of 6 to 10 units, inclusive.” This wording makes it perfectly clear that both endpoints of the range, 6 and 10, lie within the range subject to the 20-percent price discount. You still need to review a set of similar requirements to make sure the range endpoints don’t overlap, though. For example, note the inconsistency between the following two requirements:

The system shall calculate a 20% discount on orders of 6 to 10 units, inclusive.
The system shall calculate a 30% discount on orders of 10 to 20 units, inclusive.

The boundary value of 10 is incorrectly included in both ranges. Using a table to show this sort of information is more concise and makes these kinds of errors more evident:

Units Purchased	Discount Percentage
1-5	0
6-10	20
11-20	30
21+	40

The final article in this series on writing high-quality requirements deals with several fiendish sources of requirements ambiguity: synonyms, pronouns, abbreviations, adverbs, and others.

Don’t forget to leave your comments below.

Elements of Requirements Style, Part 2

Written by Karl Wiegers on December 4, 2012. Posted in Articles. 1 Comment on Elements of Requirements Style, Part 2

This is the second in a series of four articles on writing high-quality requirements. The first article in the series discussed the use of the keyword “shall” when writing requirements and offered frameworks for writing functional requirements from the perspective of either the system or the user.

Parent and Child Requirements

When writing requirements in a hierarchical fashion, the BA records a parent requirement and one or more child requirements. The parent requirement is satisfied by implementing all of its children. Here’s an illustration of a hierarchical requirement with some problems:

3.4 The requester shall enter a charge number for each chemical ordered.

3.4.1 The system shall validate charge numbers against the master corporate charge number list. If the charge number is invalid, the system shall notify the requester and shall not accept the order.

3.4.2 The charge number entered shall apply to an entire order, not to individual line items in the order.

Notice that this parent requirement, 3.4, is written in the form of a functional requirement. It’s not entirely clear how many requirements are represented here: two or three? Also notice that there is a conflict between the parent requirement and one of its child requirements, 3.4.2. If each ordered chemical is a line item, exactly how many charge numbers is the requester supposed to enter?

These sorts of problems disappear if the parent requirement is written in the form of a heading or title instead of in the form of a functional requirement. Consider using this style whenever you have a set of child requirements that, in the aggregate, constitute a parent requirement. Following is an improved version of the preceding example:

3.4 Charge Numbers

3.4.1 The requester shall enter a charge number for each chemical in an order.

3.4.2 The system shall validate charge numbers against the master corporate charge number list. If the charge number is not found on this list, the system shall notify the requester and shall not accept the order.

What Was That Again?

Ambiguity is the great bugaboo of software requirements. Ambiguity shows up in two forms. One form I can catch myself. I read a requirement and realize that I can interpret it in more than one way. I don’t know which interpretation is correct, but at least I caught the ambiguity.

The other type of ambiguity is much harder to spot. Suppose the BA gives the requirements specification to several reviewers. The reviewers encounter an ambiguous requirement that makes sense to each of them but means something different to each of them. The reviewers all report back, “These requirements are fine.” They didn’t find the ambiguity because each reviewer knows only his own interpretation of that requirement. Let’s see some sources of ambiguity to watch for and some suggestions about how to write less ambiguous requirements.

Complex Logic

Complex Boolean logic offers many opportunities for ambiguities and missing requirements. Consider the following paragraph:

If an order is placed for a chemical to a vendor, the system shall check to see if there are any other pending orders for that chemical. If there are, the system shall display the vendor name, vendor catalog number, and the name of the person who placed each previous order. If the user wishes to contact any person who placed a previous order, the system shall allow the user to send that person an e-mail message.

This long requirement is difficult to read and contains multiple functionality descriptions that should be split into separate requirements. Plus, it has some gaps. Writing requirements in this style makes it difficult to see whether the outcomes of all the if/then branches are specified. “Else” conditions are often overlooked with this sort of textual representation. Nested “or”, “and”, and “not” clauses are better represented using a decision table or decision tree.

A decision tree such as that shown in Figure 1 would immediately reveal that the system’s behavior is not specified if there are no pending orders for that particular chemical. Other false outcomes from the decisions are also unspecified. Implicitly, perhaps the reader will conclude that the system should do nothing if the various “if” conditions described here are false, but that’s an assumption forced by the incompleteness.

Figure 1. Sample decision tree for complex logic.

Expressions involving compound operators—such as “IF this AND (that OR the other)”—are even more confusing:

If the amount of the cash refund is less than $50 or the amount of the cash refund is $50 or greater and the current user is a supervisor, then the system shall open the cash register drawer.
Making this requirement understandable and unambiguous requires either parentheses (awkward) or splitting into multiple requirements (better).

Negative Requirements

Negative (or inverse) requirements are another source of confusion. Try to recast inverse requirements in a positive sense, to state what the system will do under certain circumstances. Table 1 states several functional requirements, all drawn from actual projects, that contain negation, along with possible ways to rewrite them in a positive sense. I’ve also restated these passive-voice requirements into the less ambiguous active voice, which clearly shows what entity is taking each action. Note that changing a negative requirement into a positive one often requires inserting the word only to identify the conditions that permit the system action being described to take place. In the third example, note also the ambiguity between cannot (as in “not able to”) and may not (as in “not permitted to”).

Table 1. Removing Negation from Functional Requirements

Avoid double and triple negatives in all circumstances. Consider this example:

Training rewards and points will not be visible to users who cannot participate in training rewards.

We can rephrase this double negative into a positive statement that’s easier to understand:

The system shall display training rewards and points only to users who are permitted to participate in training rewards.

Following is another illustration of recasting a double negative into a positive using an “only” constraint. The original requirement said:

Users who are delivered service without being authenticated should not generate accounting records.

Let’s state it as a positive action that the developer can actually implement:

The system shall generate accounting records only for users who are delivered service after being authenticated.

Multiple negations can lead to ambiguous requirements, as illustrated here:

Records, however, should not fail validation if these attributes are not present at all.

Does this mean that the records should fail validation if the attributes are present? Probably not. The context might make the meaning of this requirement clearer, but as it’s written, it raises a question in my mind.

The main message here is to think positive when writing requirements!

Don’t forget to leave your comments below.

Elements of Requirements Style, Part 1

Written by Karl Wiegers on November 6, 2012. Posted in Articles. 1 Comment on Elements of Requirements Style, Part 1

Writing requirements is hard! There is no simple, formulaic approach to software specification. High-quality requirements begin with proper grammar, accurate spelling, well-constructed sentences, and a logical organization. This series of four articles, adapted from my book More about Software Requirements (Microsoft Press, 2006), presents numerous style guidelines to keep in mind when writing functional requirements.

I’m not a fan of arbitrary rules about writing requirements. Some I’ve heard are:

A requirement may not contain the word and. An “and” indicates the presence of two requirements, which must be separated.
A requirement may not contain more than one sentence.
A requirement may not contain more than 22 words.

These sorts of simplistic rules are intended to help analysts write good requirements, but there are too many cases in which they don’t constitute good advice. As you develop your requirements specifications, remember your key objective: clear and effective communication among the project stakeholders.

I Shall Call This a Requirement

Shall is the traditional keyword for identifying a functional requirement. Functional requirements describe behaviors the system shall exhibit under certain circumstances or actions the system shall let the user take. Some people object to the use of shall because it feels stilted. It’s not the way people normally talk, at least not outside English period-piece movies. True—but so what? In fact, this is a plus. Using a distinctive word sharply separates a requirement from other information in a specification document. Shall serves as a symbol that signals the presence of a discrete requirement.

Too many requirements specifications use a random mix of different verbs: shall, must, should, could, would, is recommended, is desirable, is requested, will, can, may, and might. Many of these words are used interchangeably in casual conversation, but this can become confusing in a written specification. The reader is left to wonder whether there’s a subtle but important distinction between these various keywords. Does must have some different connotation than can? Does might (which conveys a sense of possibility in normal dialog) mean the same thing as may (which conveys a sense of permission)? I’ve also heard of conventions in which shall identifies a requirement, but will indicates a design statement and must signifies a constraint. Oh, my.

Some organizations follow a convention I find risky. In this scheme, shall indicates a function that is required, should means that the function is desired, and may indicates that the function being described is optional. This raises two problems. First, two concepts are being combined: the statement of intended functionality and the relative priority of that functionality. The second problem is that the priority information is being communicated using words that have similar meanings in everyday conversation.

My preference is to use the keyword shall to identify functional requirements whenever possible. Avoid should, may, might, and similar words that don’t make it clear whether the statement is a requirement. My colleague Brian Lawrence suggests that you replace should with probably won’t and see if that would be all right with the customer. It probably won’t.

A requirement in the form, “The system should do X” can be restated in the form, “When Y happens, the system shall do X.” And instead of using the shall–should–may convention to communicate priority, I’d rather see requirements written as follows:

“The system shall … [Priority = High].”
“The system shall … [Priority = Medium].”
“The system shall … [Priority = Low].”

The goal of clear and unambiguous communication is more elusive when requirements writers use a mix of nearly synonymous verbs and expect all readers to reach the same conclusions about what they’re trying to say. Frankly, I don’t understand the objection to shall. But if you don’t like it, pick an alternative word—such as must—and use it consistently.

System Perspective or User Perspective?

Various conventions for writing functional requirements exist. Some people believe that requirements should describe only the system’s behavior, because “the system” is what you create by implementing all the functional requirements. However, I think it’s appropriate to write functional requirements from either the system’s perspective or the user’s perspective. Use whichever structure offers the clearest communication in a given situation.

Requirements written from the system’s perspective conform to the following general structure:

Conditions: “When [some conditions are true]…”
Result: “… the system shall [do something]”
Qualifier: “…[response time goal or quality objective].”

The “conditions” part of the requirement could reflect an event that triggers the system to respond in some way. Here’s a simple example, from an information system for ordering meals on-line from a company cafeteria:

“When the patron indicates that he does not wish to order any more food items, the system shall display all food items ordered, the individual food item prices, and the total payment amount within 1 second.”

This requirement describes an event that the system can detect, followed by the action the system takes in response to that event. This requirement also includes a performance goal, the 1-second response time. This element constitutes a nonfunctional requirement associated with this specific bit of system functionality.

When stating such performance goals, it’s important to make clear whether they are critical values or merely desirable targets. Is the system acceptable if it takes 1.2 seconds to display the order details? How about 10 seconds? Precise response times are more critical for hard real-time systems than for information systems.

In some cases, it makes more sense to describe actions that the system will let the user take under particular circumstances. When writing functional requirements from the user’s perspective, keep the following general structure in mind:

User type: “The [user class or actor name]…”
Result type: “… shall be able to [do something]…”
Object: “… [to something].
Qualifier: [response time goal or quality objective]

It’s more meaningful to refer to the affected user class by name, rather just saying user. Here’s an illustration of a functional requirement written from the user’s perspective:

“The patron shall be able to reorder any meal he had ordered within the previous six months, provided that all food items in that order are available on the menu for the meal date.”

Note that these examples are written in the active voice. They explicitly identify the entity—the system or a specific user type—that takes each action. Most of the functional requirements I read are written in passive voice:

Passive: “When the output state changes, it is logged in the event log.”

Whenever you can, recast such requirements in the much clearer active voice:

Active: “When the output state changes, the system shall record the new state and the time of the state change in the event log.”

With active voice, the reader doesn’t have to deduce which entity is doing what. The more explicit and precise you can make the requirements, the easier it will be for the readers to understand them and use them to guide the project work they do.

The next article in this series addresses parent-child requirement relationships and two common sources of requirements problems: complex logic and negative requirements.

Don’t forget to leave your comments below.