How to Write Requirements

There are many formal languages, notations, and layouts for writing requirements; these including specialized diagrams, logics, and more. Because the study of these notations is a subject in its own right, in this course we will stick to English, sometimes stylized.

Irrespective of what language you use, it's essential to remember the following:

Requirements are about the problem, not the solution. This will be the single hardest mistake you will have to learn to avoid. Any references to specific technologies, for instance, must be present because the problem demands it, not because you think it would be a nice way to solve the problem.
Requirements come from the user. There may actually be many kinds of users (e.g., in a burger chain, both the customers and the counter staff are “users” of any solution you implement for franchise locations, but in very different ways), and some of the people you consult may not be “users” in the strict sense of the word at all (e.g., the management of the burger chain may never eat at their own franchises). For this reason people prefer to use the term “stakeholders”. This is suitably broad (e.g., the people who own stock in the burger chain are also stakeholders, and probably do have some expectations for what you build), but this term is so ugly and clichéd that we'll try to avoid it.
Requirements can assume many forms. Some directly prescribe desired functionality; others describe expectations of behavior outside the desired functionality; still others represent constraints imposed by the solution domain. Formally, people use terms like functional requirements, non-functional requirements, pseudo requirements, and so forth to describe these. We won't ask you to be quite so formal, but we do want you to be cognizant of these distinctions.
Requirements should be available in a form that can be read by the user. You want your users to read your requirements and agree that it reflects their desires. (Note that this does not immediately preclude using formal notations: some users are perfectly capable of reading formalism, and formalism has the benefit of precision and unambiguity.)

Use Cases

In this course, we'll ask you to write requirements as use cases. You can, and should, read more about them on Wikipedia and elsewhere on the Web. This is only an overview.

Example Task

Design and build a cash register for a fast-food chain.

First, we must identify the participants in the system. The participants may not all be humans; indeed, in some systems very few of them are. For instance, in an automobile control system, the participants include the wheels, engine, steering, various sensors and actuators...and only incidentally the driver. These are all typically called actors.

Example Actors

Walk-In Customers, Drive-Up Customers, Cash Register, Food Preparation Workers, Counter Staff, Drive-Up Window Staff, Branch Managers, Store, Location Owners, Franchise Management, Franchies Stockholders.

Comment: As this example illustrates, there may be hierarchies and relationships amongst actors. For instance, it is sometimes necessary to differentiate between different kinds of customers, but at other times it is convenient to refer to them customers uniformly. Thus, object-oriented design (which does not necessarily have to be implemented as an object-oriented program) uses is-a (a Walk-In Customer is-a Customer) and has-a (a Store has a Branch Manager) relations to model actors.

Actors engage in actions. We identify examples of these actions, called scenarios. A scenario describes which actors are involved and a sequence of actions or events. When describing a scenario, take into account both the necessary and the available information and stimuli. Scenarios are concrete.

Example Scenario

Name: OrderAtRegister

Actors: Walk-In Customers (c), Counter Staff (s), Cash Register (r)
Goal: c want to place an order by paying s
Events:

c approach counter.

s greets c.

c state desired order.

s enters order data into r.

s asks c how they wish to pay.

s processes payment with r.

s makes r print receipt.

s hands a member of c the receipt, repeating the order designator.

s thanks c and acknowledges any response.

If c are still in front of console, s points to pick-up area to indicate where order will be available.

s shifts gaze to next available customer or to console in order to prompt c to move on.

c moves to food pick-up area.

Comment: This looks fairly straight-forward; how many more scenarios can there be? Well, let's think. Did you notice that even if a group of people showed up together, there was only one payment? Sometimes a group arrives at the counter together, is greeted just once, but each member pays separately. Sometimes a customer orders an item, then changes their mind. Sometimes a customer asks for a change that requires an override from a manager (who wasn't part of the above scenario at all). A customer might ask a question that requires an inquiry made to the kitchen or the manager. A customer might present a coupon. A customer might place an order for something not in stock. A customer might get an emergency call, leave, and return hours later for their food! So this scenario really should have been called SimpleOrderAtRegister. And we haven't begun to account for drive-up orders, perhaps phone-in orders, etc.

Finally, we collect groups of related scenarios into use cases. A use case generalizes is a collection of related scenarios. It is meant to capture all the possible behaviors related to some functionality. It drops detail specific to individual scenarios, and generalizes over their commonality. A use case can refer to other use cases, rather like procedures invoking one another.

Gathering scenarios into use cases is a fine art. If we generalize too little, we don't get useful abstractions (and find ourselves with too many use cases). If we generalize too much, there is too little detail for the user to comment on (or find flaws in). There is no single right answer, so try several groupings before settling on one; also be aware that different parts of the development process will care about different groupings.

Example Use Case

Name: TakingOrder

Actors: Customers, Order Staff, Branch Manager, Food Preparation Workers, Cash Register
Initiator: Customers
Events:

Customers approach Order Staff.

Order Staff greets Customers.

Customers and Order Staff execute OrderStatement using Cash Register.

Order Staff, Food Preparation Workers, and Manager execute FoodClarification, if necessary.
Order Staff and Customers execute PaymentNegotiation. using Cash Register

Order Staff engages Branch Manager in Order Reconciliation, if necessary.

Order Staff issues Customers order acknowledgment from Cash Register.

Order Staff thanks Customers and acknowledges any response.

Order Staff shifts attention to next Customers.

Customers move to collect order.

Comment: We have generalized all ordering scenarios into one use case. From one perspective, this is great: it captures what is common to both walk-in and drive-in orders while eliminating all their differences. On the other hand, it also masks huge physical differences of location, lines of sight, and means of mobility. The person who eventually designs the database may not care, but the person who builds the physical interface probably does.

As you record these scenarios and abstract them, you may find that some information you obtain doesn't fit into any one work-flow. In particular, you will find expectations about behaviors under all circumstances. Don't lose these; record them separately! They will eventually lead to system tests.

Example System Expectations

Order confirmation must take under 30 seconds.

Each order item should be visible for up to ¹/₂ a second.

The cash register must use techniques to prevent fraud.

The cash register must tolerate up to one minute of power outage.

The cash register cannot be down for more than one minute every day, and must be able to operate every day of the year.

The cash register should cost under $250 in 2009 dollars.

Comment: The implementation of some of these expectations will already be manifest in the scenarios. Others, however, may not be reflected in any of them, because they are at a different level of abstraction than the scenarios reflect, or their implementation requires the interaction of many different parts of the system. Preserving these as a separate check-list that must be obeyed by all implementations helps us avoid losing them.

Finally, you will encounter one other kind of information: statements about the operating environment. Record these separately: they tell the system designers what they can expect and rely upon. (In some cases, the environment may not provide enough for the designer to provide what is expected!)

Example Operating Environment

The Store has a backup generator.

Order Staff may operate the register wearing latex gloves.

The Store may have WiFi running.

Comment: Notice that we haven't said anything about the uninterrupted availability of power (the generator may need to be operated manually). Therefore, the designer of the cash register will probably need to include some sort of battery facility. But this, in turn, may drive costs above the upper-bound specified.

Level of Detail

The Wikipedia article gives an extensive template for what one might put in a use case (and, similarly, in a scenario). You don't need to (and probably shouldn't) use all of these for every single scenario and use case: use your discretion. However, you may find the template a useful checklist. Some of the entries may remind you of aspects that you hadn't thought of initially, and may force you to revisit information or perhaps even ask additional questions of users. At any rate, remember that verbosity can be the enemy of readability, and you ultimately want your users to read your use cases!