Requirements Shell

The requirements shell is a guide to writing each atomic requirement (see Figure B.1). The components of the shell (also called a "snow card") are discussed fully in Chapter 10, Writing the Requirements.

1. The Purpose of the Project

1a. The User Business or Background of the Project Effort

Content

Content, Motivation, Examples, and Considerations

A short description of the business being done, its context, and the situation that triggered the development effort. It should also describe the work that the user intends to do with the delivered product.

Motivation

Without this statement, the project lacks justification and direction.

Considerations

You should consider whether the user problem is serious, and whether and why it needs to be solved.

1b. Goals of the Project

Content

This boils down to one sentence, or at most a few sentences, that say why we want this product. Here is where you state the real reason the product is being developed.

Motivation

There is a danger that this purpose may get lost along the way. As the development effort heats up, and as the customer and developers discover more about what is possible, the system could potentially wander away from the original goals as it undergoes construction. This is a bad thing unless there is some deliberate act by the client to change the goals. It may be necessary to appoint a person to be custodian of the goals, but it is probably sufficient to make the goals public and periodically remind the developers of them. It should be mandatory to acknowledge the goals at every review session.

Examples

We want to give immediate and complete response to customers who order our goods over the telephone.

We want to be able to forecast the weather.

Measurement

Any reasonable goal must be measurable. This is necessary if you are ever to test whether you have succeeded with the project. The measurement must quantify the advantage gained by the business through doing the project. If the project is worthwhile, there must be some solid business reason for doing it. For example, if the goal of the project is

We want to give immediate and complete response to customers who order our goods over the telephone.

you have to ask what advantage that goal brings to the organization. If immediate response will result in more satisfied customers, then the measurement must quantify that satisfaction. For example, you could measure the increase in repeat business (on the basis that a happy customer comes back for more), the increase in customer approval ratings from surveys, the increase in revenue from returning customers, and so on.

It is crucial to the rest of the development effort that the goal is firmly established, is reasonable, and is measured. It is usually the latter that makes the former possible.

2. The Client, the Customer, and Other Stakeholders

2a. The Client

Content

This item gives the name of the client. It is permissible to have several names, but having more than three negates the point.

Motivation

The client has the final say on acceptance of the product, and thus must be satisfied with the product as delivered. You can think of the client as the person who makes the investment in the product. Where the product is being developed for in-house consumption, the roles of the client and the customer are often filled by the same person. If you cannot find a name for your client, then perhaps you should not be building the product.

Considerations

Sometimes, when building a package or a product for external users, the client is the marketing department. In this case, a person from the marketing department must be named as the client.

2b. The Customer

Content

The person intended to buy the product. In the case of in-house development, the client and the customer are often the same person. In the case of development of a mass-market product, this section contains a description of the kind of person who is likely to buy the product.

Motivation

The customer is ultimately responsible for deciding whether to buy the product from the client. The correct requirements can be gathered only if you understand the customer and his aspirations when it comes to using your product.

2c. Other Stakeholders

Content

The roles and (if possible) names of other people and organizations who are affected by the product, or whose input is needed to build the product.

Examples of stakeholders:

• Sponsor

• Testers

• Business analysts

• Technology experts

• System designers

• Marketing experts

• Legal experts

• Domain experts

• Usability experts

• Representatives of external associations

For a complete checklist, download the stakeholder analysis template at www.volere.co.uk.

For each type of stakeholder, provide the following information:

• Stakeholder identification (some combination of role/job title, person name, and organization name)

• Knowledge needed by the project

• The degree of involvement necessary for that stakeholder/knowledge combination

• The degree of influence for that stakeholder/knowledge combination

• Agreement on how to address conflicts between stakeholders who have an interest in the same knowledge

Motivation

Failure to recognize stakeholders results in missing requirements.

3. Users of the Product

3a. The Hands-On Users of the Product

Content

A list of a special type of stakeholderthe potential users of the product. For each category of user, provide the following information:

• User name/category: Most likely the name of a user group, such as schoolchildren, road engineers, or project managers.

• User role: Summarizes the users' responsibilities.

• Subject matter experience: Summarizes the users' knowledge of the business. Rate as novice, journeyman, or master.

• Technological experience: Describes the users' experience with relevant technology. Rate as novice, journeyman, or master.

• Other user characteristics: Describe any characteristics of the users that have an effect on the requirements and eventual design of the product. For example:

- Physical abilities/disabilities

- Intellectual abilities/disabilities

- Attitude toward job

- Attitude toward technology

- Education

- Linguistic skills

- Age group

- Gender

Motivation

Users are human beings who interface with the product in some way. Use the characteristics of the users to define the usability requirements for the product. Users are also known as actors.

Examples

Users can come from wide variety of (sometimes unexpected) sources. Consider the possibility of your users being clerical staff, shop workers, managers, highly trained operators, the general public, casual users, passers-by, illiterate people, tradesmen, students, test engineers, foreigners, children, lawyers, remote users, people using the system over the telephone or an Internet connection, emergency workers, and so on.

3b. Priorities Assigned to Users

Content

Attach a priority to each category of user. This gives the importance and precedence of the user. Prioritize the users as follows:

• Key users: They are critical to the continued success of the product. Give greater importance to requirements generated by this category of user.

• Secondary users: They will use the product, but their opinion of it has no effect on its long-term success. Where there is a conflict between secondary users' requirements and those of key users, the key users take precedence.

• Unimportant users: This category of user is given the lowest priority. It includes infrequent, unauthorized, and unskilled users, as well as people who misuse the product.

The percentage of the type of user is intended to assess the amount of consideration given to each category of user.

Motivation

If some users are considered to be more important to the product or to the organization, then this preference should be stated because it should affect the way that you design the product. For instance, you need to know if there is a large customer group who has specifically asked for the product, and for which, if they do not get what they want, the results could be a significant loss of business.

Some users may be listed as having no impact on the product. These users will make use of the product, but have no vested interest in it. In other words, these users will not complain, nor will they contribute. Any special requirements from these users will have a lower design priority.

3c. User Participation

Content

Where appropriate, attach to the category of user a statement of the participation that you think will be necessary for those users to provide the requirements. Describe the contribution that you expect these users to providefor example, business knowledge, interface prototyping, or usability requirements. If possible, assess the minimum amount of time that these users must spend for you to be able to determine the complete requirements.

Motivation

Many projects fail through lack of user participation, sometimes because the required degree of participation was not made clear. When people have to make a choice between getting their everyday work done and working on a new project, the everyday work usually takes priority. This requirement makes it clear, from the outset, that specified user resources must be allocated to the project.

3d. Maintenance Users and Service Technicians

Content

Maintenance users are a special type of hands-on users who have requirements that are specific to maintaining and changing the product.

Motivation

Many of these requirements will be discovered by considering the various types of maintenance requirements detailed in section 14. However, if we define the characteristics of the people who maintain the product, it will help to trigger requirements that might otherwise be missed.

4. Mandated Constraints

This section describes constraints on the eventual design of the product. They are the same as other requirements except that constraints are mandated, usually at the beginning of the project. Constraints have a description, rationale, and fit criterion, and generally are written in the same format as functional and nonfunctional requirements.

4a. Solution Constraints

Content

This specifies constraints on the way that the problem must be solved. Describe the mandated technology or solution. Include any appropriate version numbers. You should also explain the reason for using the technology.

Motivation

To identify constraints that guide the final product. Your client, customer, or user may have design preferences, or only certain solutions may be acceptable. If these constraints are not met, your solution is not acceptable.

Examples

Constraints are written using the same form as other atomic requirements (refer to the requirements shell for the attributes). It is important for each constraint to have a rationale and a fit criterion, as they help to expose false constraints (solutions masquerading as constraints). Also, you will usually find that a constraint affects the entire product rather than one or more product use cases.

Description: The product shall use the current two-way radio system to communicate with the drivers in their trucks.

Rationale: The client will not pay for a new radio system, nor are any other means of communication available to the drivers.

Fit Criterion: All signals generated by the product shall be audible and understandable by all drivers via their two-way radio system.

Description: The product shall operate using Windows XP.

Rationale: The client uses XP and does not wish to change.

Fit Criterion: The product shall be approved as XP compliant by the MS testing group.

Description: The product shall be a hand-held device.

Rationale: The product is to be marketed to hikers and mountain climbers.

Fit Criterion: The product shall weigh no more than 300 grams, no dimension shall be more than 15 centimeters, and there shall be no external power source.

Considerations

We want to define the boundaries within which we can solve the problem. Be careful, because anyone who has experience with or exposure to a piece of technology tends to see requirements in terms of that technology. This tendency leads people to impose solution constraints for the wrong reason, making it very easy for false constraints to creep into a specification. The solution constraints should only be those that are absolutely non-negotiable. In other words, however you solve this problem, you must use this particular technology. Any other solution would be unacceptable.

4b. Implementation Environment of the Current System

Content

This describes the technological and physical environment in which the product is to be installed. It includes automated, mechanical, organizational, and other devices, along with the nonhuman adjacent systems.

Motivation

To describe the technological environment into which the product must fit. The environment places design constraints on the product. This part of the specification provides enough information about the environment for the designers to make the product successfully interact with its surrounding technology.

The operational requirements are derived from this description.

Examples

Examples can be shown as a diagram, with some kind of icon to represent each separate device or person (processor). Draw arrows to identify the interfaces between the processors, and annotate them with their form and content.

Considerations

All component parts of the current system, regardless of their type, should be included in the description of the implementation environment.

If the product is to affect, or be important to, the current organization, then include an organization chart.

4c. Partner or Collaborative Applications

Content

This describes applications that are not part of the product but with which the product will collaborate. They can be external applications, commercial packages, or preexisting in-house applications.

Motivation

To provide information about design constraints caused by using partner applications. By describing or modeling these partner applications, you discover and highlight potential problems of integration.

Examples

This section can be completed by including written descriptions, models, or references to other specifications. The descriptions must include a full specification of all interfaces that have an effect on the product.

Considerations

Examine the work context model to determine whether any of the adjacent systems should be treated as partner applications. It might also be necessary to examine some of the details of the work to discover relevant partner applications.

4d. Off-the-Shelf Software

Content

This describes commercial, open source, or any other off-the-shelf software (OTS) that must be used to implement some of the requirements for the product. It could also apply to nonsoftware OTS components such as hardware or any other commercial product that is intended as part of the solution.

Motivation

To identify and describe existing commercial, free, open source, or other products to be incorporated into the eventual product. The characteristics, behavior, and interfaces of the package are design constraints.

Examples

This section can be completed by including written descriptions, models, or references to supplier's specifications.

Considerations

When gathering requirements, you may discover requirements that conflict with the behavior and characteristics of the OTS software. Keep in mind that the use of OTS software was mandated before the full extent of the requirements became known. In light of your discoveries, you must consider whether the OTS product is a viable choice. If the use of the OTS software is not negotiable, then the conflicting requirements must be discarded.

Note that your strategy for discovering requirements is affected by the decision to use OTS software. In this situation you investigate the work context in parallel with making comparisons with the capabilities of the OTS product. Depending on the comprehensibility of the OTS software, you might be able to discover the matches or mismatches without having to write each of the business requirements in atomic detail. The mismatches are the requirements that you will need to specify so that you can decide whether to satisfy them by either modifying the OTS software or modifying the business requirements.

Given the spate of lawsuits in the software arena, you should consider whether any legal implications might arise from your use of OTS. You can cover this in section 17, Legal Requirements.

4e. Anticipated Workplace Environment

Content

This describes the workplace in which the users are to work and use the product. It should describe any features of the workplace that could have an effect on the design of the product, and the social and culture of the workplace.

Motivation

To identify characteristics of the workplace so that the product is designed to compensate for any difficulties.

Examples

The printer is a considerable distance from the user's desk. This constraint suggests that printed output should be deemphasized.

The workplace is noisy, so audible signals might not work.

The workplace is outside, so the product must be weather resistant, have displays that are visible in sunlight, and allow for the effect of wind on any paper output.

The product is to be used in a library; it must be extra quiet.

The product is a photocopier to be used by an environmentally conscious organization; it must work with recycled paper.

The user will be standing up or working in positions where he must hold the product. This suggests a hand-held product, but only a careful study of the users' work and workplace will provide the necessary input to identifying the operational requirements.

Considerations

The physical work environment constrains the way that work is done. The product should overcome whatever difficulties exist; however, you might consider a redesign of the workplace as an alternative to having the product compensate for it.

Schedule Constraints

Content

Any known deadlines, or windows of opportunity, should be stated here.

Motivation

To identify critical times and dates that have an effect on product requirements. If the deadline is short, then the requirements must be kept to whatever can be built within the time allowed.

Examples

• To meet scheduled software releases.

• There may be other parts of the business or other software products that are dependent on this product.

• Windows of marketing opportunity.

• Scheduled changes to the business that will use your product. For example, the organization may be starting up a new factory and your product is needed before production can commence.

Considerations

State deadline limitations by giving the date and describing why it is critical. Also, identify prior dates where parts of your product need to be available for testing.

You should also ask questions about the impact of not meeting the deadline:

• What happens if we don't build the product by the end of the calendar year?

• What is the financial impact of not having the product by the beginning of the Christmas buying season?

4g. Budget Constraints

Content

The budget for the project, expressed in money or available resources.

Motivation

The requirements must not exceed the budget. This limitation may constrain the number of requirements that can be included in the product.

The intention of this question is to determine whether the product is really wanted.

Considerations

Is it realistic to build a product within this budget? If the answer to this question is no, then either the client is not really committed to building the product or the client does not place enough value on the product. In either case you should consider whether it is worthwhile continuing.

5. Naming Conventions and Definitions

5a. Definitions of All Terms, Including Acronyms, Used in the Project

Content

A glossary containing the meanings of all names, acronyms, and abbreviations used within the requirements specification. Select names carefully to avoid giving a different, unintended meaning.

This glossary reflects the terminology in current use within the work area. You might also build on the standard names used within your industry.

For each term, write a succinct definition. The appropriate stakeholders must agree on this definition.

Avoid abbreviations, as they introduce ambiguity, require additional translations, and could potentially lead to misinterpretation in the mind of anyone who is trying to understand your requirements. Ask your requirements analysts to replace all abbreviations with the correct term. This is easily done with word processors.

Acronyms are acceptable if they are completely explained by a definition.

Motivation

Names are very important. They invoke meanings that, if carefully defined, can save hours of explanations. Attention to names at this stage of the project helps to highlight misunderstandings.

The glossary produced during requirements is used and extended throughout the project.

Examples

Truck: A vehicle used for spreading de-icing material on roads. "Truck" is not used to refer to goods-carrying vehicles.

BIS: Business Intelligence Service. The department run by Steven Peters to supply business intelligence for the rest of the organization.

Considerations

Make use of existing references and data dictionaries. Obviously, it is best to avoid renaming existing items unless they are so ambiguous that they cause confusion.

From the beginning of the project, emphasize the need to avoid homonyms and synonyms. Explain how they increase the cost of the project.

5b. Data Dictionary for Any Included Models

Content

Dictionary definitions of all information flows and stores used in models. Particular consideration should be given to defining the data attributes of all flows shown the context models (see sections 7 and 8).

This section should also contain any technical specifications for interfaces shown on the context models.

Motivation

The context diagram provides an accurate definition of the scope of the work being studied or the scope of the product to be built. This definition can be completely accurate only if the information flows bordering the scope have their attributes defined.

Examples

Road de-icing schedule = issue number + {road section identifier + treatment start time + critical start time + truck identifier} + depot identifier

As you progress through the requirements specification, define each of the elementary terms in detail.

Considerations

The dictionary provides a link between the requirements analysts and the implementers. The implementers add implementation details to the terms in the dictionary, defining how the data will be implemented. Also, implementers add terms that are present because of the chosen technology and that are independent of the business requirements.

6. Relevant Facts and Assumptions

6a. Facts

Content

Factors that have an effect on the product, but are not mandated requirements constraints. They could be business rules, organizational systems, or any other activities that have an effect on this product. Facts are things you want the reader of the specification to know.

Motivation

Relevant facts provide background information to the specification readers, and might contribute to requirements. They will have an effect on the eventual design of the product.

Examples

One ton of de-icing material will treat three miles of single-lane roadway.

The existing application is 10,000 lines of C code.

6b. Assumptions

Content

A list of the assumptions that the developers are making. These assumptions might be about the intended operational environment, but can be about anything that has an effect on the product. As part of managing expectations, assumptions also contain statements about what the product will not do.

Motivation

To make people declare the assumptions that they are making. Also, to make everyone on the project aware of assumptions that have already been made.

Examples

• Assumptions about new laws or political decisions.

• Assumptions about what your developers expect to be ready in time for them to usefor example, other parts of your products, the com-pletion of other projects, software tools, or software components.

• Assumptions about the technological environment in which the product will operate. These assumptions should highlight areas of expected compatibility.

• The software components that will be available to the developers.

• Other products being developed at the same time as this one.

• The availability and capability of bought-in components.

• Dependencies on computer systems or people external to this project.

• The requirements that will specifically not be carried out by the product.

Considerations

We often make unconscious assumptions. It is necessary to talk to the members of the project team to discover any unconscious assumptions that they have made. Ask stakeholders (both technical and business-related) questions such as these:

• What software tools are you expecting to beavailable?

• Will there be any new software products?

• Are you expecting to use a current product in a new way?

• Are there any business changes you are assuming we will be able to deal with?

It is important to state these assumptions up front. You might also consider the probability of whether the assumption is correct and, where relevant, a list of alternatives if something that is assumed does not happen.

The assumptions are intended to be transient. That is, they should all be cleared by the time the specification is releasedthe assumption should have become either a requirement or a constraint. For example, if the assumption related to the capability of a product that is intended to be a partner product to yours, then the capability should have been proven satisfactory, and it becomes a constraint to use it. Conversely, if the bought-in product is not suitable, then it becomes a requirement for the project team to construct the needed capability.

7. The Scope of the Work

7a. The Current Situation

Content

This is an analysis of the existing business processes, including the manual and automated processes that might be replaced or changed by the new product. Business analysts might already have done this investigation as part of the business case analysis for the project.

Motivation

If your project intends to make changes to an existing manual or automated system, you need to understand the effect of proposed changes. The study of the current situation provides the basis for understanding the effects of proposed changes and choosing the best alternatives.

7b. The Context of the Work

Content

The work context diagram identifies the work that you need to investigate to be able to build the product. Note that it includes more than the intended product. Unless we understand the work that the product will support, we have little chance of building a product that will fit cleanly into its environment.

The adjacent systems on the context diagram in Figure B.2 (e.g., Weather Forecasting Service) indicate other subject matter domains (systems, people, and organizations) that need to be understood. The interfaces between the adjacent systems and the work context indicate why we are interested in the adjacent system. In the case of Weather Forecasting Service, we can say that we are interested in the details of when, how, where, who, what, and why it produces the District Weather Forecasts information.

Figure B.2. This context diagram shows the scope of the work to be studied.

Motivation

To clearly define the boundaries for the study of the work and requirements effort. Without this definition, we have little chance of building a product that will fit seamlessly into its environment.

Considerations

The names used on the context diagram should be consistent with the naming conventions and data dictionary definitions presented in section 5. Without these definitions, the context model lacks the required rigor, and it may be misunderstood. Relevant stakeholders must agree to the definitions of the interfaces shown on the context model.

7c. Work Partitioning

Content

A list showing all business events to which the work responds. Business events are happenings in the real world that affect the work. They also happen because it is time for the work to do somethingfor example, produce weekly reports, remind nonpaying customers, check the status of a device, and so on. The response to each event is called a business use case; it represents a discrete partition of work that contributes to the total functionality of the work.

The event list includes the following elements:

• Event name

• Input from adjacent systems (identical with name on context diagram)

• Output to adjacent systems (identical with name on context diagram)

• Brief summary of the business use case (This is optional, but we have found it is a very useful first step in defining the requirements for the business use caseyou can think of it as a mini-scenario.)

Motivation

To identify logical chunks of the system that can be used as the basis for discovering detailed requirements. These business events also provide the subsystems that can be used as the basis for managing detailed analysis and design.

Table B.1. Busisness Event List

Event Name	Input and Output	Summary
1. Weather Station transmits reading	Weather Station Readings (in)	Record the readings as belonging to the weather station.
2. Weather Service forecasts weather	District Weather Forecast (in)	Record the forecast.
3. Road engineers advise changed roads	Changed Road (in)	Record the new or changed road. Check that all appropriate weather stations are attached.
4. Road Engineering installs new Weather Station	New Weather Station (in)	Record the weather station and attach it to the appropriate roads.
5. Road Engineering changes Weather Station	Changed Weather Station (in)	Record the changes to the weather station.
6. Time to test Weather Stations	Failed Weather Station Alert (out)	Determine if any weather stations have not transmitted for two hours, and inform Road Engineering of any failures.
7. Truck Depot changes a truck	Truck Change (in)	Record the changes to the truck.
8. Time to detect icy roads	Road De-icing Schedule (out)	Predict the ice situation for the next two hours. Assign a truck to any roads that will freeze. Issue the schedule.
9. Truck treats a road	Treated Road (in)	Record the road as being in a safe condition for the next three hours.
10. Truck Depot reports problem with truck	Truck Breakdown (in) Amended Gritting Schedule (out)	Reassign available trucks to the previously assigned roads.
11. Time to monitor road treatment	Untreated Road Reminder (out)	Check that all scheduled roads have been treated in the assigned time, and issue reminders for any untreated roads.

Considerations

Attempting to list the business events is a way of testing the work context. This activity uncovers uncertainties and misunderstandings about the project and facilitates precise communications. When you do an event analysis, it will usually prompt you to make some changes to your work context diagram.

We suggest you gather requirements for discrete sections of the work. This requires you to partition the work, and we have found business events to be the most convenient, consistent, and natural way to break the work into manageable units.

8. The Scope of the Product

8a. Product Boundary

A use case diagram identifies the boundaries between the users (actors) and the product. You arrive at the product boundary by inspecting each business use case and determining, in conjunction with the appropriate stakeholders, which part of the business use case should be automated (or satisfied by some sort of product) and what part should be done by the user. This task must take into account the abilities of the actors (section 3), the constraints (section 4), the goals of the project (section 1), and your knowledge of both the work and the technology that can make the best contribution to the work.

The use case diagram (see Figure B.3) shows the actors outside the product boundary (the rectangle). The product use cases are the ellipses inside the boundary. The lines denote usage. Note that actors can be either automated or human.

Figure B.3. The use cases for the IceBreaker case study.

Example

Derive the product use cases by deciding where the product boundary should be for each business use case. These decisions are based on your knowledge of the work and the requirements constraints.

8b. Product Use Case List

The use case diagram is a graphical way of summarizing the product use cases relevant to the product. If you have a large number of product use cases (we find 1520 is a good limit), then it is better to make a list of the product use cases and model or describe each one individually.

8c. Individual Product Use Cases

This is where you keep details about the individual product use cases on your list. You can include a scenario for each product use case on your list.