Objective 1: Understand What to Build

This may sound strange , but the fact is that in many projects there is no common understanding of what needs to be built. Although all team members may think they know, often each one has a completely different understanding than the next . If you want to succeed, all stakeholders must agree on a common definition of success. You need to make sure that customers, management, analysts, developers, testers, technical writers, and other key people involved agree on what system to build.

To ensure a common understanding, you need to

1. Agree on a high-level Vision.

2. Provide a "mile-wide, inch-deep" description of the system. Briefly describe what the system should do, without providing so much detail that you get bogged down or that some stakeholders, such as customers or management, lose sight of what is being built because key information is hidden in a mass of requirements documentation.

3. Detail key actors and use cases so that all stakeholders can easily understand them and team members can use them as direct input for their work.

Produce a Vision Document

To address item A, you produce a Vision Document. For very small projects, this could be an informal document, maybe even an e-mail message capturing a previous whiteboard discussion. For average- sized projects, you might write a Vision Document of a few pages. No matter what the format is, a Vision should clarify to stakeholders

• The benefits and opportunities that will be provided by building the application.

• The problem(s) the application will solve.

• Who the target users are.

• At a very high level, what the product will do, expressed as high-level features or in terms of outlining a few key use cases.

• Some of the most essential nonfunctional requirements, such as supported operating systems, database support, required reliability, scalability, and quality, as well as licensing and pricing, if that is relevant.

The Vision creates the foundation for a common understanding of the motivation for building the system, as well as a high-level definition of the system to be built. The Vision should be complete and stable at the end of Inception, but you will continue refining it throughout the project, especially in Elaboration and early Construction (if there is a significant change of scope). It is important that the Vision is public, shared, and constantly reviewed, so that no one can say he or she didn't know or understand it. The widely used Statement of Work (SOW) is somewhat analogous to parts of the Vision.

For more information, see the section Develop a Vision, in Chapter 15.

Generate a "Mile-Wide, Inch-Deep" Description

As item B specifies, you need to provide a good description of the system's scope without going into too much detail. The description requires two basic activities:

• Identify and briefly describe actors. Identify typical users for your system, and classify them based on what they do and what services they expect. Identify also other systems with which yours will interact. Capture these user types and external systems as actors.

• Identify and briefly describe use cases. Identify and describe how each actor will interact with the system. If the actor is a human, then describe typical ways the actor will use the system. Descriptions of these typical interactions with the system are called use cases.

At this stage, do not get into too many details: A description a couple of paragraphs long is sufficient for most use cases. However, you could spend a little more time on the use cases you identify as the most critical (and they should not be more than 20 percent of the total number) so that you have a solid understanding of them.

Hold a Workshop or Brainstorming Session

So, how do you produce this mile-wide, inch-deep description? For small projects, you get your team, your customer, and maybe other stakeholders together for a brainstorming meeting of a few hours. For larger projects, you may do a two-day workshop that includes all key stakeholders: project manager, architect, lead developer, customer, and a couple of analysts. During this session, your goal is to complete the seven steps that follow. Note that you do the steps in an iterative fashion, meaning that you will revisit these steps several times in Inception. It is often useful to "time-box" each step, that is, assign a fixed amount of time you will dedicate to it. As you run out of time on a step, go to the next step, and revisit the previous steps at a later stage. This will prevent participants from becoming too involved in one issue, forgetting that you want to achieve breadth more than depth. Note that if you have a brainstorming meeting, you will spend less time on each step, especially step 4. Have people work on step 4 after the meeting, and then have a follow-up meeting where you revisit steps 4 “7.

Step 1. Identify as many actors as you can (remember, actors represent both users and external systems with which the system interacts ). Throughout Inception and Elaboration you will eliminate some actors that are not needed, merge some actors that have similar needs, and add some additional actors you forgot . Write a one- sentence description of actors.

Step 2. Associate each actor with use cases, capturing the actor's interactions with the system by providing a brief description of the use case.

Step 3. For each of the use cases, determine whether it requires interaction with other users or systems. This will help you identify additional actors. Continue to go back and forth between finding actors and use cases until you think you have identified enough to understand the scope of the system. You most likely have not gotten them all, but it is good enough at this stage.

When you've completed these first three steps, your results will probably look similar to those shown in the use-case diagram in Figure 6.2.

Step 4. Write a paragraph describing each actor and a couple of paragraphs about each use case. This can be done as a break-out session in which each person in the workshop is given two hours to describe, for example, one actor and two to three use cases. Make sure there is overlap; that is, the same use case and actors are given to several participants to describe. Then reassemble the group and review all descriptions. At this point you may encounter an interesting phenomenon : Although everyone agrees on the use-case names , each person has his or her own interpretation of what the use case entails. With detailed, written descriptions, these different interpretations become clear; by comparing them, you can see whether you need to come up with a few more use cases to cover all the functionality needed.

Step 5. Create a Glossary containing the key "items" the application deals with. For an insurance application, for example, you'd want to define things such as claims, different types of policies, and so on. Also add common terminology that is used in the domain and that the team or stakeholders may not be familiar with. This glossary should help the participants agree on a common terminology as this is often a cause of miscommunication and misunderstanding.

Step 6. Review key items that the system is dealing with, and make sure you have created use cases that detail how each key item is created, maintained , and deleted. Do you have a use case that describes how to set up a policy? How to make changes to a policy? How to cancel a policy? This is a great way of discovering holes in your use-case model, and spending only 30 minutes on this activity will often get you a long way.

Step 7. At this stage, you need to identify the most essential or critical use cases (maybe only one or two, and at most 20 percent of your use cases). See the section Identify Key System Functionality for more details.

Figure 6.2. System Overview: User Kinds and Their Use Cases. During a use-case workshop, capture (on a whiteboard) the user groups and systems (actors) that will interact with your system and the services (use cases) your system will provide to those actors.

For more information, see the section Describe Requirements "Mile-Wide, Inch-Deep," in Chapter 15.

Detail Key Actors and Use Cases

Another step in understanding what you must build is to refine some of the use cases. At the end of the workshop or brainstorming session, you assign one or several use cases to each analyst, who will describe in further detail essential or critical use cases identified in step 7. Typically, you'll generate a couple of pages for each one. The higher the ceremony, the more detailed the description.

For more information on detailing actors and use cases, see the section Detail Actors and Use Cases, in Chapter 15.

In parallel to writing the use-case descriptions, you should also develop user-interface prototypes. This allows you to visualize the flow of events, making sure that you, the users, and other stakeholders understand and agree on the flow of events. See the section Develop User-Interface Prototypes , in Chapter 15, for more information.

You should time-box the activities on use cases to avoid getting bogged down into too much detail. You should also focus on capturing the most essential flow of events and point out the existence of alternative flows of events (because it will help you to assess how complex the use case is to implement), rather than describing the details of each flow of events.

Especially for small projects, you often have the same person take on the role of analyst and developer, meaning that the person who describes a use case will also implement it. If so, you may want to spend less time on documenting the detailed requirements and come back to them as you implement the use case. It is still very useful to identify alternative flows of events, since this will be useful to you when you estimate the amount of work remaining.

For each of our three example projects, the teams do the following:

• Project Ganymede, a small green-field project: The project manager/architect spends a day writing a three-page Vision Document. The team spends half a day in a brainstorming session to come up with an initial set of actors and use cases. Thirteen use cases are found, and each team member takes four to five use cases, spending 30 minutes to detail each use case. Then they get together and realize that they need another four use cases. They merge two use cases and eliminate one. They spend another two hours describing each of the four most critical use cases (see the section Objective 2: Identify Key System Functionality).

• Project Mars, a large green-field project: In the first iteration, the analysts, involving key stakeholders as necessary, spend roughly a week writing a first-draft Vision of eight pages. A lot of time is spent getting buy-in from all stakeholders. The team spends two days on a use-case workshop with eight key stakeholders, allowing them to come up with a good first-draft use-case model and glossary. In the second iteration, the team refines the Vision, which will be further refined later in the project, especially in Elaboration. They spend roughly four hours describing each of the nine most critical use cases (see the following section, Objective 2: Identify Key System Functionality). In conjunction with doing that, they make a number of updates to the use-case model.

• Project Jupiter, a second generation of a large project: The team makes some updates to the existing Vision, clearly labeling what will be accomplished in the second generation, which is done in a day or two. Most of the time is spent on making an inventory of additional capabilities to implement and the known problems in the first system that must be fixed. The team tries to identify use cases that need to be added, and the most critical of the new use cases are detailed, with the team spending two to four hours on each of them. Planned improvements to existing use cases are listed, but these improvements are normally not detailed at this stage.