Home > Articles > Software Development & Management > Agile

  • Print
  • + Share This
  • 💬 Discuss
This chapter is from the book

This chapter is from the book

3.2 DESIGN SCOPE

Design scope is the extent of the system—I would say "spatial extent" if software took up space. It is the set of systems, hardware and software, that we are charged with designing or discussing; it is that boundary. If we are to design an ATM, we are to produce hardware and software that sits in a box—the box and everything in it is ours to design. The computer network that the box will talk to is not ours to design—it is out of the design scope.

From now on, when I write scope alone, I mean design scope. This is because the functional scope is adequately defined by the actor-goal list and the use cases, while the design scope is a topic of concern in every use case.

As the following story illustrates, it is very important that the writer and reader are in agreement about the design scope for a use case—and correct. The price of being wrong can be a factor of two or more in cost, with disastrous results for the outcome of a contract. The readers of a use case must quickly see what you intend to be inside the system boundary. That will not be obvious just from the name of the use case or the primary actor. Systems of different sizes show up even within the same use case set.

Typically, writers consider the scope of the system to be so obvious that they don't mention it. However, once there are multiple writers and multiple readers, the design scope of a use case is not obvious at all. One writer is thinking of the entire corporation as the scope (see Figure 3.1), one is thinking of all of the company's software systems, one is thinking of the new, client–server system, and one is thinking of only the client or only the server. Readers, having no clue as to what is meant, get lost or misunderstand the document.

Figure 3.1 Design scope can be any size

What can we do to clear up the misunderstanding?

A Short, True Story

To help with constructing a fixed-time, fixed-cost bid of a large system, we were walking through some sample designs. I picked up the printer and spoke its function. The IS expert laughed. "You personal computer people crack me up, "he said," You think we just use a little laser printer to print our invoices? We have a huge printing system, with a chain printer, batch I/O, and everything. We produce invoices by the boxful!"

I was shocked. "You mean the printer is not in the scope of the system?"

"Of course not! We'll use the printing system we already have."

Indeed, we found that there was a complicated interface to the printing system. Our system was to prepare a magnetic tape with things to be printed. Overnight, the printing system would read the tape and print what it could. It would prepare a reply tape describing the results of the printing job, with error records for anything it couldn't print. The following day, our system would read back the results and note what had not been printed correctly. The design job for interfacing to that tape was significant, and completely different from what we had been expecting.

The printing system was not for us to design, but was for us to use. It was out of our design scope. (It was, as described in Section 3.3, a supporting actor.) Had we not detected this mistake, we would have written the use case to include it in our scope and turned in a bid to build more system than was needed.

The only answer I have found is to label each and every use case with its design scope, using specific names for the most significant scopes. To be concrete, let us suppose that MyTelCo is designing a NewApp system, which includes a Searcher subsystem. The design scope names are these:

  • Enterprise (i.e., MyTelCo). You are discussing the behavior of the entire organization or enterprise in delivering the goal of the primary actor. Label the Scope field of the use case with the name of the organization—MyTelCo—rather than just "the company." If discussing a department, use the department name. Business use cases are written at the enterprise scope.

  • System (i.e., NewApp). This is the piece of hardware or software you are charged with building. Outside the system are all the pieces of hardware, software, and humanity that the system is to interface with.

  • Subsystem (i.e., Searcher). You have opened up the main system and are about to talk about how a piece of it works.

Using Graphical Icons to Highlight the Design Scope

Consider attaching a graphic to the left of the use case title to signal the design scope to readers before they start reading. There are no tools at this time to manage the icons, but I find that drawing them reduces confusion. In this book I label each use case with its appropriate icon to make it easier for you to note its scope.

As you read the following list, remember that a black-box use case does not discuss the internal structure of the system under discussion while a white-box use case does.

  • A business use case has the enterprise as its scope. Its graphic is a building. Color it grey () if you treat the whole enterprise as a black box. Color it white () if you talk about the departments and staff within the organization.

  • A system use case has a computer system as its scope. Its graphic is a box. Color it grey () if you treat it as a black box, white () if you reveal how its componentry works.

  • A component use case is about a subsystem or component of the system under Its graphic is a bolt. See Use Cases 13 through 17 for an example.

Design Scope Examples

I offer three examples to illustrate systems at different scopes.

(1) Enterprise-to-System Scope

Suppose that we work for telephone company, MyTelCo, which is designing a new system, Acura, to take orders for services and upgrades. Acura consists of a workstation connected to a server. The server will be connected to a mainframe running the old system, BSSO. BSSO is just a terminal attached to the mainframe. We are not allowed to make any changes to it; we can only use its existing interfaces.

The primary actors for Acura include the customer, the clerk, various managers, and BSSO (we are clear that BSSO is not within our scope).

Let's find a few of the goals the system should support. The most obvious is "Add a new service." We decide that the primary actor for that is the company clerk, acting on behalf of the customer. We sit down to write a few use cases.

The immediate question is "What is the system under discussion?" It turns out that there are two that interest us:

  • MyTelCo. We are interested in the question, "What does MyTelCo's service look like to the customer, showing the new service implementation in its complete form, from initial request to implementation and delivery?" This question is of double interest. The company managers will want to see how the new system appears to the outside world, and the implementation team will want to see the context in which the new system will sit. This use case will be written at the enterprise scope (), with the Scope field labeled MyTelCo and the use case written without mention of company-internal players (no clerks, no departments, no computers). This sort of use case is often referred to as a business use case, since it is about the business.

  • Acura. We are interested in the question, "How does Acura's service appear, at its interface to the clerk or customer on one side and to the BSSO system on the other side?" This is the use case the designers care most about, since it states exactly what they are to build. The use case will be written at the system scope (), with the Scope field labeled "Acura." It will freely mention clerks and departments and other computer systems, but not the workstation and the server subsystems.

We produce two use cases. To avoid having to repeat the same information twice, we write the enterprise use case at a higher level (the kite symbol), showing MyTelCo responding to the request, delivering it, and perhaps even charging for it and getting paid. The purpose of the enterprise use case is to show the context around the new system. Then we describe in detail the 5- to 20-minute handling of the request in the user-goal use case having Acura as its scope.

Use Case 6 Add New Service (Enterprise)

Primary Actor: Customer

Scope: MyTelCo

Level: Summary

  1. Customer calls MyTelCo, requests new service . . .

  2. MyTelCo delivers . . . etc. . . .

Use Case 7 Add New Service (Acura)

Primary Actor: Clerk for external customer

Scope: Acura

Level: User goal

  1. Customer calls in, clerk discusses request with customer.

  2. Clerk finds customer in Acura.

  3. Acura presents customer's current service package . . . etc. . . .

No use case will be written with a scope of Acura workstation or Acura server, as these are not of interest to us. Later, someone in the design team may choose to document Acura's subsystem design using use cases. At that time, they will write two use cases, one with a scope of Acura workstation, the other with a scope of Acura server. My experience is that these use cases are never written, since there are other adequate techniques for documenting subsystem architecture.

(2) Many Computers to One Application

The following is a less common situation, but one that is very difficult. Let us build onto the MyTelCo situation.

Acura will slowly replace BSSO. New service requests will be put into Acura and then modified using BSSO. Over time, Acura will take on more function. The two systems must co-exist and synchronize with each other. Thus, use cases have to be written for both systems: Acura being entirely new and BSSO being modified to synchronize with it.

The difficulty in this situation is that there are four use cases, two for Acura and two for BSSO. There is one use case for each system having the clerk as primary actor and one having the other computer system as the primary actor. There is no way to avoid these four use cases, but people looking at them get confused because they look redundant.

To document this situation, I first write a summary-level use case whose scope is both computer systems. This gives me a chance to document their interactions over time. In that use case, I reference the specific use cases that comprise each system's requirements. This first use case will be of the white-box type (note the white-box symbol).

The situation is complicated enough that I also include diagrams of each use case's scope.

Use Case 8 Enter and Update Requests (Joint System)

Primary Actor: Clerk for external customer

Scope: Computer systems, including Acura and BSSO (see diagram)

Level: Summary

Main Success Scenario:

  1. Clerk adds new service into Acura.

  2. Acura notes new service request in BSSO.

  3. Some time later, Clerk updates service request in BSSO.

  4. BSSO notes the updated request in Acura.

The four sub use cases are all user-goal use cases and get marked with the sealevel symbol. Although they are all system use cases, they are for different systems—hence the diagrams. In each diagram, I circle the primary actor and shade the SuD. The use cases are black-box this time, since they are requirements for new work. In addition, I give them slightly different verb names, using the verb "note" to indicate one system synchronizing with the other.

Use Case 9 Add New Service (into Acura)

Primary Actor: Clerk for external customer

Scope: Acura

Level: User goal

. . . use case body follows. . .

Use Case 10 Note New Service Request (in BSSO)

Primary Actor: Acura

Scope: BSSO

Level: User goal

. . . use case body follows. . .

Use Case 11 Update Service Request (in BSSO)

Primary Actor: Clerk for external customer

Scope: BSSO

Level: User goal

. . . use case body follows. . .

Use Case 12 Note Updated Request (in Acura)

Primary Actor: BSSO

Scope: Acura

Level: User Goal

. . . use case body follows. . .

If you are using UML use case diagrams, you might draw the summary-level use case instead of writing it. That still does not reduce the confusion within the four user-goal use cases, so you should still carefully mark their primary actor, scope, and level, and possibly still draw the scope diagrams within the use cases.

Figure 3.2 Use case diagrams for Acura–BSSO. This is the UML style of denoting the interactions between the two systems. The upper section shows that BSSO is a supporting actor to one use case of Acura and a primary actor to another use case. In the lower diagram, the roles are reversed.

Personally, I do not find that this eliminates much confusion. I would consider drawing the nonstandard use case diagram in Figure 3.3 to show the connection between the two systems. This diagram is clearer but harder to maintain over time. Draw whichever you and your readers find communicates best for you.

Figure 3.3 A combined use case diagram for Acura-BSSO. This drawing shows the relationships of the four use cases most clearly, but is nonstandard, since it shows one system's use case triggering another system's use case.

(3) Nuts and Bolts Use Cases

At the far end of the scale, let's look at the way one group documented their design framework with use cases. They started with an 18-page, diagram-loaded description of the rules for their framework. They decided it was too hard to read and experimented with use cases as the descriptive technique.

The group spent one week on the task. First they drafted 40 use cases to make sure they had captured all the requests their framework would handle. Using extensions and the data variations list, they revised those down to just six.

Most readers will find these use cases incomprehensible because they are not in that business. However, I expect some readers to be technical programmers looking for ways to document their designs, so I include these use cases to show how this group documented an internal architecture and how they made use of the variations list. I find them fairly easy to read, given the complexity of their problem. Notice that sub use cases are underlined. Thanks to Dale Margel in Calgary for the writing.

General Description:

The overall architecture must be able to handle concurrent tasks. To do this, it must support Process Threads and Resource Locking. These services are handled by the Concurrency Service Framework (CSF). CSF is used by client objects to protect critical sections of code from unsafe access by multiple processes.

Use Case 13 Serialize Access to a Resource

Primary Actor: Service Client object

Scope: Concurrency Service Framework (CSF)

Level: User goal

Main Success Scenario:

  1. Service Client asks a Resource Lock to give it specified access.

  2. The Resource Lock returns control to the Service Client so that it may use the Resource.

  3. Service Client uses the Resource.

  4. Service Client informs the Resource Lock that it is finished with the Resource.

  5. Resource Lock cleans up after the Service Client.

Extensions:

2a.

Resource Lock finds that Service Client already has access to the resource:

2a1.

Resource Lock applies a lock conversion policy (Use Case 14) to the request.

2b.

Resource Lock finds that the resource is already in use:

2b1.

The Resource Lock applies a compatibility policy (Use Case 15) to grant access to the Service Client.

2c.

Resource Locking Holding time limit is nonzero:

2c1.

Resource Lock starts the holding timer.

3a.

Holding Timer expires before the Client informs the Resource Lock that it is finished:

3a1.

Resource Lock sends an Exception to the Client's process.

3a2.

Fail!

4a.

Resource Lock finds nonzero lock count on Service Client:

4a1.

Resource Lock decrements the reference count of the request.

4a2.

Success!

5a.

Resource Lock finds that the resource is currently not in use:

5a1.

Resource Lock applies an access selection policy (Use Case 16) to grant access to any suspended service clients.

5b.

Holding Timer is still running:

5b1.

Resource Lock cancels Holding Timer.


Technology and Data Variations List:

  1. The specified requested access can be:

    • For exclusive access

    • For shared access

  2. The lock holding time-out can be specified by:

    • The Service Client

    • A Resource Locking policy

    • A global default value

Use Case 14 Apply a Lock Conversion Policy

Primary Actor: Client object

Scope: Concurrency Service Framework (CSF)

Level: Subfunction

Main Success Scenario:

  1. Resource Lock verifies that request is for exclusive access.

  2. Resource Lock verifies that Service Client already has shared access.

  3. Resource Lock verifies that there is no Service Client waiting to upgrade access.

  4. Resource Lock verifies that there are no other Service Clients sharing the resource.

  5. Resource Lock grants Service Client exclusive access to the resource.

  6. Resource Lock increments Service Client lock count.

Extensions:

1a.

Resource Lock finds that the request is for shared access:

1a1.

Resource Lock increments lock count on Service Client.

1a2.

Success!

2a.

Resource Lock finds that the Service Client already has exclusive access:

2a1.

Resource Lock increments lock count on Service Client.

2a2.

Success!

3a.

Resource Lock finds that there is another Service Client waiting to upgrade access:

3a1.

Signal Service Client that requested access could not be granted.

3a2.

Fail!

4a.

Resource Lock finds that there are other Service Clients using the resource:

4a1.

Resource Lock makes Service Client wait for resource access (Use Case 17).


Use Case 15 Apply an Access Compatibility Policy

Primary Actor: Service Client object

Scope: Concurrency Service Framework (CSF)

Level: Subfunction

Main Success Scenario:

  1. Resource Lock verifies that request is for shared access.

  2. Resource Lock verifies that all current usage of resource is for shared access.

Extensions:

2a.

Resource Lock finds that the request is for exclusive access:

2a1.

Resource Lock makes Service Client wait for resource access (Use Case 17) (the process is resumed later by the Lock serving strategy).

2b.

Resource Lock finds that the resource is being exclusively used:

2b1.

Resource Lock makes Service Client wait for resource access (Use Case 17)


Variations:

  1. The compatibility criterion may be changed.

Use Case 16 Apply an Access Selection Policy

Primary Actor: Client object

Scope: Concurrency Service Framework (CSF)

Level: Subfunction

Main Success Scenario:

Goal in Context: Resource Lock must determine which (if any) waiting requests should be served.

Note

This strategy is a point of variability.

  1. Resource Lock selects oldest waiting request.

  2. Resource Lock grants access to selected request(s) by making its process runnable.

Extensions:

1a.

Resource Lock finds no waiting requests:

1a1.

Success!

1b.

Resource Lock finds a request waiting to be upgraded from a shared to an exclusive access:

1b1.

Resource Lock selects the upgrading request.

1c.

Resource Lock selects a request that is for shared access:

1c1.

Resource repeats [Step 1] until the next one is for exclusive access.


Variations:

  1. The selection ordering criterion may be changed.

Use Case 17 Make Service Client Wait for Resource Access

Primary Actor: Client object

Scope: Concurrency Service Framework (CSF)

Level: Subfunction

Main Success Scenario:

Used By: CC 2,4 Resource Locking:

  1. Resource Lock suspends Service Client process.

  2. Service Client waits until resumed.

  3. Service Client process is resumed.

Extensions:

1a.

Resource Lock finds that a waiting time-out has been specified:

1a1.

Resource Lock starts timer.

2a.

Waiting Timer expires:

2a1.

Signal Service Client that requested access could not be granted.

2a2.

Fail!


Technology and Data Variations List:

 

 

1a1.

The Lock waiting time-out can be specified by: u The Service Client u A Resource Locking policy u A global default value


  • + Share This
  • 🔖 Save To Your Account

Discussions

comments powered by Disqus