Ah, the smell of newly opened packing material in the morning. You just received a rather large shipment from the front desk, and now sitting on your desk is an unwrapped set of disks and manuals with “ClearQuest” written all over them. Where do you start? How do you design a successful ClearQuest deployment? Well, the best place to start is by outlining the problem domain and then reaching an understanding of all the pieces to the puzzle. Think of it as a holistic approach to problem solving: Before attempting to solve any kind of problem, it’s always good to map out all of the artifacts in the system, define the relationships among the artifacts, and figure out the best solution with the broadest perspective.
Without question, the time and effort spent in up-front planning saves time and effort down the road. Adequate time and resources should always be made available for planning your project.
[A.5.1] Before understanding how to use ClearQuest, you first need to understand who will be using the application. It’s always best to do a bit of planning before moving forward with an implementation, so let’s start with a use case analysis of your development system. When defining the components of your system, where is the best place to start? You should always start with the actors.
Actors are the ClearQuest users or relevant systems (the “who” or the “what”) that will use—or be used by—ClearQuest.
If you come from a very process-oriented organization, just had a lot of time on your hands, and have already started with your own development system analysis, good—you’re ahead of the game. Basically, draw a circle around your ClearQuest actor and pull whatever use cases you have already created from your analysis.
If you’re starting from scratch, the first step is to list each user type that will be accessing your new ClearQuest system. Table 5-1 provides some examples of common actors you might encounter, with each of their primary responsibilities.
Table 5-1. Human Actors
Actor | Description |
|---|---|
Administrator | The ClearQuest administrator keeps everything up and running. The administrator usually makes changes to the design, database schema, and implementation. |
Customer | This is the customer of the product that your team will be developing (i.e., the end user). The customer may need reports from ClearQuest or direct access to the enhancements or defects that he or she has reported. |
Change control board (CCB) | Change control boards are commonly used to monitor and track the changes being managed for the upcoming product release. |
Developer | The software developer is responsible for making changes to the software as it relates to enhancements or defects. |
Tester | The tester will (hopefully) find all of the defects and report them before the product goes out the door. Testers are responsible for validating any changes to the product in the released builds of the product. |
Tech writer | The tech writer is responsible for changing the documentation to describe new enhancements to the product or to correct errors found in the documentation. |
Manager | The manager is responsible for making the team more productive. The manager typically assigns change requests to individual developers, tech writers, or testers. |
Business analyst | The analyst may work with the product or engineering teams to help define internal processes or could be an external customer liaison in solution definition and development who needs access to the system. |
Obviously, this list is not exhaustive. Your organization may also involve several roles within the product management organization, or you may want to include field representatives. The key here is to write down everything you can at this time; in other words, document as much as you understand about the current system and all the actors that may need access to the system. Don’t worry about trying to determine what each of these actors will be doing in the system (submitting, reviewing, and so on). It’s easier to remove actors once you have all the components defined. Later in the process, you will determine which actors interact with ClearQuest and which ones don’t, so it’s better to err on the side of too much information now rather than trying to add an actor later.
Humans are not the only actors that interact with ClearQuest. The software that will integrate with ClearQuest is just as important to document as the human actors. Table 5-2 provides examples of software that could be part of a development system with ClearQuest.
Table 5-2. Software Actors
Actor | Description |
|---|---|
Microsoft Project | Microsoft Project keeps track of the projects; it can be integrated with ClearQuest to show the amount of time spent on individual tasks to fix a defect or enhancement. This gives the manager a better mechanism for predicting completion of the product. |
ClearCase | The version control system should be tied to the changes made in the system; in other words, it should correlate to defects and enhancements. |
RequisitePro | RequisitePro keeps track of requirements. Some of these requirements turn into enhancements for the product. |
Legacy bug system | The current defect-tracking system contains information that will need to be put into ClearQuest. |
Remedy (CRM system) | Customer support typically has another system to keep track of calls and also the changes that need to be made to the product. |
Figure 5-1 shows the typical set of actors associated with ClearQuest.
A use case is a sequence of actions that an actor performs within a system—in this case, ClearQuest—to achieve a particular goal. A good use case should describe one aspect of the system without presuming any specific design or implementation. In other words, a use case describes what the system needs to do without specifying how the system will perform.
Here’s an example of good use case text:
The data entry clerk types his or her user ID and password and then submits this information to the system. The system ensures that the user ID is valid and that the password matches the stored user ID, and then. . . .
And here’s an example of bad use case text:
The data entry clerk types his or her user ID and password and then presses the OK button (located in the lower right-hand corner of the window). The system goes out to the SystemUser table and uses the entered user ID as the key into the table. . . .
The text of a use case describes possible paths through the use case. This text includes the actions that the actor performs and the system’s responses to those actions. These paths are captured as flows of events.
Two kinds of flows of events are associated with use cases.
The main flow of events (sometimes referred to as the basic course of action) is the sunny-day scenario, the main start-to-finish path that the actor and the system will follow under normal circumstances. The assumption is that the primary actor doesn’t make any mistakes, and the system generates no errors. A use case always has a main flow of events.
An exceptional flow of events (or alternate course of action) is a path through a use case that represents an error condition or a path that the actor and the system take less frequently. A use case often has at least one exceptional flow of events; in fact, the more interesting behavior described by use cases is often found in the alternate courses.
The basic idea is this: Each use case should address one or more requirements in text that’s easy to understand quickly for everyone involved in the project, whether technically savvy or not.
Use cases provide very important benefits to your planning efforts. For one, they help you visualize the problem space and the relationships of the various actors. For another, they help you identify any missing actors. They also force you to think about the various steps in your existing process and whether those steps will meet your needs when ClearQuest has been fully implemented—or whether you’re going to need to make some changes.
Taking the actors described earlier, we can quickly find some use cases that each actor can perform with respect to the implementation of ClearQuest. Figure 5-2 illustrates some examples of the use cases found in a standard ClearQuest implementation.
Your use cases should include some descriptive text or scenarios that show how each actor interacts with the system. Here are some examples.
Create Defect: The customer or tester creates a defect by defining a title of the defect, a description, the severity of the defect, the type of defect, the product version, the product build, and the date by which the defect should be resolved.
Create Enhancement: The customer creates an enhancement request for the product. He or she specifies a title for the enhancement, a description, the criticality of the enhancement, the version of the product he or she is using, and the date by which he or she would like to have the enhancement.
Assign Change Request: A change request is created when a developer or tech writer is assigned to perform work toward an enhancement or a defect. The manager assigns the change request.
Approve Change Request: When the developer or tech writer makes a change to the product, he or she will advise the change control board that the change is ready for review before it gets integrated into the system.
Integrate Change Request: The developer or tech writer integrates the change request into the product using ClearCase UCM once the change control board has approved the change for integration.
This should make sense whether or not you are well versed in the Unified Modeling Language (UML) and use case analysis. If you follow these steps, we promise that you’ll have a better understanding of your current systems and users and how best to deploy ClearQuest.
You can also use this information to develop the workflows, which will help you determine just how you will need to customize ClearQuest to fit your needs.
An activity diagram is a variation on the traditional flowchart. In the context of ClearQuest, we’ll use activity diagrams to illustrate workflows between use cases.
On an activity diagram, a use case is represented by a sort of lozenge shape—a symbol with long, straight lines on top and bottom and short sides that are curved outward (see Figure 5-3). Other features of activity diagrams include branching and merging, as well as forking and joining.
A branch is a decision point at which there are two or more possible paths of flow of control. A merge is a point at which two branched paths come together. Both branches and merges appear as diamonds, just as branches do on flowcharts.
A fork is a splitting of a flow of control into two or more flows of control, each of which operates independent of and concurrent with the others. A join is a synchronization of two or more flows of control into one flow. Both forks and joins are represented as long, thin, black rectangles called synchronization bars.
An activity diagram can also show swimlanes. Each pair of these lines, which are generally vertical, delineates one group of activities or use cases. These are very useful for showing which part of an organization or which specific actors are involved in which use cases within your workflow.
You should begin mapping your workflows by examining the use cases you specified earlier. Include an activity for each use case, and add a swimlane for each actor using the given use case.
Next, draw the typical flow of activities among the use cases. In most cases, you will find that you need to add more activities than you have use cases. Again, don’t worry about the amount of content at this stage—it’s all part of the refinement process.
In Figure 5-3, we’ve added a few additional activities to help round out a typical flow of activities and to help you understand how to approach your model.
Now that our high-level use case workflow or activity diagram is complete, we can look at more detailed activity diagrams. You should continue to elaborate (a fancy word that means to refine or to build upon) the workflow until you have enough information that you can show the end users of the system—and those folks who will be actually designing and deploying the system—just what the system will be doing. This is where the “art” of deployment comes into play: With too little finessing, you could end up developing something the users don’t want, whereas too much creativity in your planning process could waste your own time. Don’t fall victim to analysis paralysis. The key is to elaborate just enough.
This is rather vague, we know, but there is no definitive stopping point. At some time, you need to draw the line and move forward with your implementation.
One important elaboration involves starting to find the objects involved in the workflow so that you can easily change the workflow, adding data objects and their proposed states to the high-level activity diagram. An object flow is simply a dependency that shows the details of how the object(s) involved in the various activities or use cases on the diagram are specifically affected.
In Figure 5-4, we add three objects, along with the state each object is in, during the workflow. Remember, this is still a very high-level depiction.
[A.5.2] What’s the use of implementing a new application or system if you can’t generate reports for management? OK, you may also have some use for pulling metrics out of ClearQuest—it wouldn’t be unheard of. Let’s face it: People like to look at lists.
The key here is to talk to the actors that will be using the system and ask them the following questions.
What types of reports will the users need?
What do the reports look like?
What kind of information is important for the users?
Does the information need to be in detailed or summarized form?
When will the users need to see this information?
Can the users use a website to see the information, or do they need the application installed?
How often will the users see the report?
Still not convinced that you need reports out of your system? Well, someone somewhere may eventually ask you for a report, so you might as well be prepared. Common reports that people use in defect/enhancement-tracking systems include the following:
Open change requests assigned to me: Shows the user what work he or she needs to do for a given day, week, or month
Open defects or enhancements for a specific version of the product: Shows what defects or enhancements need to be resolved for a version of the product; typically used by the manager to see the progress of work
Defects or enhancements that need review: Typically used by a change control board to see what changes need to be reviewed for approval or rejection
Defects or enhancements that have been integrated into a product: Typically used to see how much work has been accomplished for a given version of the product
Defects or enhancements submitted by a customer: Typically used by customers to find out when a defect or enhancement will be resolved and available in the product
Trends of defects: Shows open and close rates per version, for example (not the only trend that can be reported); typically used by management to determine progress on a product
Ask a user what kinds of reports he or she would like to see, and you’re going to open up a huge can of worms. The list can be very long, so try to focus on those reports that are used daily first, then weekly, and then periodically. The daily and weekly reports should be considered when designing your system, while the more periodic reports can be pushed out. ClearQuest is fairly flexible, and any missing reports or standard queries can always be added later. However, you should ask the questions, understand the requirements, and make sure the information for all of your reporting requirements are in the database in the first place.
Again, don’t go overboard on examining all of the report possibilities available to your company. Don’t get stuck in analysis paralysis. Find out which requirements are necessary and which are nice to have, and plan accordingly. Don’t worry: The topic of reports will pop up again when we elaborate the design.