Copyright 2003, 2014 Nikolas S. Boyd. Permission is granted to copy this document provided this copyright statement is retained in all copies.

Abstract

This paper introduces a new technique for capturing requirements information on index cards, including policy cards, intelligence quality cards and quantity cards, and face cards. The origins, purpose and usage of each card type are discussed, and a few representative examples are provided. Some considerations regarding how trace cards may be used in conjunction with CRC cards are also offered.

Introduction

Precedent and Context

During the late 1980s, Ward Cunningham and Kent Beck introduced the use of CRC cards¹ (Class, Responsibility, Collaborator) as a technique for capturing and sharing object-oriented design decisions. Since then, the technique has become popular among object-oriented software developers, largely due to its simplicity and effectiveness. Just as developers need a convenient way to capture and share design decisions, requirements analysts need simple ways to capture and share knowledge about business policies, business intelligence, and business activities during software development.

Language dominates software development, especially during the earliest phases of a project when the vast majority of time is spent discussing business objectives and the intended effects for a project. Ultimately, all software elements, components and composites are named, and they are often organized based on linguistic affinities, e.g., as objects and sentential expressions in object-oriented designs. So, the words used in discussions about business problems and solutions will naturally have a dramatic and durable impact on the resulting software. Beck and Cunningham emphasized this point with respect to CRC cards:

"The class name of an object creates a vocabulary for discussing a design. Indeed, many people have remarked that object design has more in common with language design than with procedural program design. We urge learners (and spend considerable time ourselves while designing) to find just the right set of words to describe our objects, a set that is internally consistent and evocative in the context of the larger design environment."

"Responsibilities identify problems to be solved. The solutions will exist in many versions and refinements. A responsibility serves as a handle for discussing potential solutions. The responsibilities of an object are expressed by a handful of short verb phrases, each containing an active verb. The more that can be expressed by these phrases, the more powerful and concise the design. Again, searching for just the right words is a valuable use of time while designing."

Perhaps even more so, discovering just the right words is valuable when capturing discussions about business policies, business intelligence, and business activities. This knowledge is the requisite fodder consumed during requirements analysis and solution design, and it establishes the context within which software solutions will be developed and evolved.

In 2003, Eric Evans introduced Domain-Driven Design,¹⁰ with a set of software design practice patterns that explicitly incorporates business and problem terminology into software designs. A key practice in DDD is the development of an ubiquitous language, shared by all members of a software development team, including developers, domain experts, solution users, owners and sponsors.

Diagrams vs. Narratives

Some methodologists have offered elaborate graphical notations for capturing knowledge about business elements and activities, e.g., the Unified Modeling Language² (UML). Such diagrams provide useful overviews and help us visualize the structural relationships between software elements, components, and composites. However, as design artifacts and residues, diagrams are expensive to create and maintain and usually require special tools. Also, they are prone to complexity and (intentionally) limited in their expressiveness.

Because of their rich structure and interconnections, most goals and usage scenarios are best expressed as structured narratives. Narratives are easy to create and maintain and usually require only simple tools, such as a text editor or hypertext (HTML) editor. Also, narratives are easier to simplify and provide the full expressiveness of natural language. Given that modern software extensively leverages language metaphors, structured narratives offer a better fit for maintaining the traceability and the expressive proximity of the resultant software to its originating requirements.

Additionally, there are systematic ways to analyze, transform, and simplify natural language statements into a form that lends itself better to software solution design. The details of such analysis are beyond the scope of this present paper. However, those interested in can find these details described in the EDUCE pattern language. ¹¹ There are several aspects of this work that are inspired in part by EDUCE.

Planning and Tracking Success

Goal Levels

Explicitly identifying the nature and level of goals can help us to align technology development with business objectives. In Writing Effective Use Cases,³ Alistair Cockburn identifies several goal levels used for requirements. However, there are certain kinds of business policies that were not included. The following proposed goal levels extend those he offered and continues the metaphor of verticality he used. These levels can also be found in my proposed conceptual model for software requirements.⁴

Table 1. Goal Levels

Level     Nature     Source Icon Vision   Policy   Governor Mission   Critical Policy   Governor Mission   Central Policy   Governor Mission   Peripheral Policy   Governor Organization   External   Customer, Partner, Supplier Organization   Internal   Requestor System   External   Expector System   Internal   Interface Designer Component   External   Component Designer

Policy Cards

A policy card may also exhibit one of two organizational variations: organized by theme and organized by subject. Card templates (1 and 2) for these two variations can be found in Appendix A.

When policy concerns are organized by theme (see Card Template 1),

• A quality / value theme abstracts a thematic concern from a vision, mission, or value statement.
• A basic measure characterizes the primary unit(s) of measure used to quantify the theme.
• The quality instantiations all share the same theme, but may have different subjects of concern.

When policy concerns are organized by subject (see Card Template 2),

• A concern subject type identifies a kind of subject: a process, a service, a product, or a policy.
• A specific concern subject identifies a specific subject of concern within the broader class.
• The qualify instantiations all share the same subject of concern, but may have different quality themes.

Policy cards can be used to capture ends statements, especially from vision and mission statements. However, ends statements differ from means statements in a subtle but significant way. Ends statements focus on effects rather than efforts. For some further remarks about ends statements and their formulation, see Quality Alignment and Quality Inventories.⁵

Policy Card Examples

Here follows discussions and example policy cards with reference to a specific worked out example problem: ECO Storage Depot. Here's a sample of how an overall corporate vision statement might be captured for the ECO Storage Depot.

Card 1. ECO Depot Vision reputation engagement count world-class hazmat storage excels in hazmat storage safety innovation, and sets the   highest standards for safe hazmat storage safety   throughout the world, resulting in     growth in storage facilities and services for client organizations worldwide

The depot is subject to external regulatory oversight by the EPA. If the depot becomes unsafe, the EPA will close it. Therefore, the continuity of depot business operations requires depot safety. To further enhance depot safety, the depot governors has established additional policies regarding depot operations.

Card 2. Safety as a Mission Theme safety regulatory compliance safe hazmat storage ensure safety compliance   minimize depot vulnerability   prevent depot closure   prevent litigation        accept all drums that can be safely stored    allocate drum storage space within licensed limits     allocate drum storage space to minimize vulnerability

These critical mission objectives can be divided into those that are externally oriented (and visible), and those that are internally oriented toward depot operations.

Card 3. Drum Storage Allocation Qualities (External) storage safety storage allocation safe storage allocation ensures regulatory compliance   prevents depot closure   prevents local litigation

Card 4. Drum Storage Allocation Qualities (Internal) storage safety storage allocation safe storage allocation accept all drums that can be safely stored    allocate drum storage space within licensed limits     allocate drum storage space to minimize vulnerability    minimize depot vulnerability

Intelligence Cards

• to capture the results of the goal, question, metric (GQM) approach,⁶
• to capture the measures identified in those metrics,⁷
• to align and trace business instrumentation requirements to business policies,
• throughout the various requirements levels.

Templates (3 and 4) for these two cards can be found in Appendix A. To link the quality and quantity cards, they both share the following information:

• A quality concern identifies a general quality area or issue of interest to a kind of stakeholder.
• A quality concern subject identifies a concern subject that needs assessment or improvement.
• An essential metric is used to measure (quantify) the quality of the concern subject.
• A stakeholder role identifies a kind of stakeholder concern about the focus quality.

A quality card (see Card Template 3) captures the following additional information:

• A stakeholder objective indicates the intended quality objective of the identified stakeholder.
• A stakeholder goal / target indicates a specific target and/or goal of the identified stakeholder.
• Each listed question helps characterize the concern subject from some stakeholder viewpoint(s).
• Each listed metric identifies the kind of measurement(s) needed to answer a listed question.

A quantity card (see Card Template 4) captures the following additional information:

• Each listed measurement identifies a characteristic needed to answer a concern question.
• Each listed quality condition identifies a relevant relation between measurements.
• Each listed source / instrument indicates the origin of a listed measurement or derivation of a listed condition.

Intelligence Card Examples

Safety of the ECO Depot has specific measurable physical criteria, constraints on the storage of hazardous chemicals that must be met to remain in compliance with EPA regulations and the additional constraints imposed by the depot governors. What are those quality constraints?

Card 5. Drum Storage Questions safety, vulnerability proximity, drum counts what makes the depot safe? no building contains disallowed drum combos     what makes the depot vulnerable? when any pair of neighboring buildings is full     how close are neighboring buildings?  when their walls are 5 meters apart or less       what makes a storage building full?  when each hazard type limit has been reached      each storage building:  has a storage license for each hazard type each building hazard type license:  limits the number of drums stored   thus, each storage building:  must have a drum storage inventory

These quality constraints may then be quantified and made measurable.

Card 6. Drum Storage Conditions and Measures vulnerability proximity, drum counts vulnerable depot = vulnerable storage building pair vulnerable buildings = neighboring pair of full storage buildings neighboring buildings = building walls within 5 meters proximity full storage building = (hazard type storage capacity = 0) per hazard type hazard type storage capacity = (drum storage limit - drum count) per hazard type building drum storage limit from: building drum storage license (per hazard type) building drum count from: building drum inventory

As well, the EPA defines the following safety criteria.

Card 7. Drum Storage Regulations safety regulatory compliance unsafe storage building = a building stores hazard type 1 and hazard type 2     safe storage building = a building stores hazard type 3 and hazard type 1   = a building stores hazard type 3 and hazard type 2

Face Cards

Face cards derive their name from their dominant focus on interfaces and interactions, the contracts and conversations that take place between interaction participants. Face cards provide a way to capture business activities and their stakeholders as use cases on index cards. A template for face cards can be found in Appendix A (see Card Template 5).

Face cards can be used as a starting point for writing use cases, or subsequently for use case analysis, especially in conjunction with agile software development methods. Detailed discussions of use cases and their components can be found in Writing Effective Use Cases³ by Alistair Cockburn. Face cards intentionally simplify use cases by eliminating some of the details that can be found in a "fully dressed" use case.

A face card captures at least the following information:

• A primary goal describes a condition expected by the primary actor when the use case completes normally.
• Each listed stakeholder interest describes a condition desired by the associated stakeholder as a want, a need, or a valued quality.
• A scenario trigger describes a condition that the trigger actor effects to initiate the use case.
• Each listed scenario step describes the action of the associated step actor that moves the scenario forward.

A face card may also capture preconditions and postconditions:

• Each listed precondition describes a condition that must be ensured by the associated guarantor prior to the inception of the use case.
• Each listed minimal guarantee describes a condition that will always be ensured as an outcome for an intended recipient or target.
• Each listed success guarantee describes a success condition that will be ensured as a result for an intended recipient or target.

There are a few features that distinguish face cards as a medium for capturing use cases. As a form of structured narrative, face cards emphasize the identification of stakeholders and their interests, their expectations, their contractual obligations, and their collaborative responsibilities.

The format of a face card reinforces this by separating the stakeholders (in the left column) from their interests, expectations, obligations, and responsibilities (in the right column). As a result, these descriptions have a distinctive narrative style. Most conditions are expressed using an active verb phrase with present tense. Two exceptions include preconditions and some triggers. Preconditions use an active verb with past tense. Some triggers may also use past tense.

When applied to a business interface, the conditions and actions often describe the business partners and their interests, their expectations, their contractual obligations, and their collaborative responsibilities. But, they may also describe value exchanges, goods exchanges, and information exchanges.

When applied at a human interface, the conditions and actions often describe the business stakeholders and their interests, their expectations, their functional obligations, and their collaborative responsibilities. But, they may also describe information exchanged between a human operator and the system under development.

When applied at a component interface, the conditions and actions often describe the clients and collaborators, and their expectations, their functional obligations, and collaborative responsibilities.

When used at these later, more detailed requirements levels, face cards can serve as an intermediate residue between use cases and designs. They can help identify candidate objects and responsibilities at human interfaces and component interfaces. This information can then be fed forward into the CRC cards used for responsibility-driven and domain-driven object-oriented design.

Here follows some representative samples of face cards for the ECO Depot. These samples are taken from a more complete set available here. These face cards show the stakeholders with their interests, the postconditions, and the main success scenarios, including the scenario initiation triggers.

Face Card Examples

Further Considerations

For example, reconsider Card 6 above. This example demonstrates how policy constraints can be analyzed for their conditions, and how apparently simple constraints can entail quite elaborate quality and measurement requirements when explored in detail. Notice that the definitions of named quality conditions often relate values and may entail further decompositions of their measurements, like the following:

full storage building =

( hazard type storage capacity = 0 ) per hazard type

Notice that this constraint requires measurements in multiple dimensions, including a licensed limit (per building, per hazard type), and an actual stored drum count (per building, per hazard type). Consequently, inventories must be maintained per building for both licenses and stored drums.

During requirements analysis (and during design), it's often useful to explore how quality themes and conditions decompose into value relations and the measurements and metrics needed to test them. Explicitly identifying and naming test conditions also improves the testability of object-oriented designs. Intelligence cards can be used to capture and share the results of such analysis. Thus, identifying and naming quality conditions and their component value relations can play an important part in ensuring software solution quality.

Perhaps this extended understanding of responsibilities can help improve our object-oriented designs, especially in the context of CRC cards. Both client and server responsibilities can be listed on a CRC card. Enumerating only the responsibilities for knowledge and behavior weakens a class design, while also enumerating the respective responsibilities of both a server and its clients strengthens a design into a contract, especially when quality responsibilities are included. This simple practice also increases the testability of the design if the quality conditions are ultimately exposed as test methods in the implementation. So, this practice can serve as a natural adjunct for test-driven development approaches like extreme programming (XP),⁹ and can also serve as a natural adjunct to language focused approaches like domain-driven design (DDD).¹⁰

Table 2. Card and Traceability Summary

References

1. Kent Beck, Ward Cunningham. A Laboratory for Teaching Object-Oriented Thinking. OOPSLA 1989 Conference Proceedings. ACM SIGPLAN Notices 24(10), 1989.

2. Object Management Group. UML™ Resource Page. http://www.uml.org/.

3. Alistair Cockburn. Writing Effective Use Cases. Addison-Wesley Publishing, Inc., 2000. ISBN 0-201-702258.

4. Nik Boyd. A Conceptual Model for Software Requirements. http://www.educery.com/papers/models/requirements.htm.

5. Nik Boyd. Quality Alignment and Quality Inventories. http://www.educery.com/papers/rhetoric/quality/alignment.htm.

6. Victor Basili, Gianluigi Caldiera, Dieter Rombach. The Goal Question Metric Paradigm. Encyclopedia of Software Engineering. John Wiley & Sons, Inc., 2001. ISBN 0-471-37737-6.

7. Scott Whitmire. Object-Oriented Design Measurement. John Wiley & Sons, Inc., 1997. ISBN 0-471-13417-1.

8. Ron Jeffries, Ann Anderson, Chet Hendrickson, Kent Beck. Extreme Programming Installed. Addison-Wesley Publishing, Inc., 2001. ISBN 0-201-70842-6.

9. Kent Beck, Extreme Programming Explained: Embrace Change. Addison-Wesley Publishing, Inc., 2000. ISBN 0-201-61641-6.

10. Eric Evans. Domain-Driven Design: Tackling Complexity in the Heart of Software. Addison-Wesley Publishing, Inc., 2003. ISBN 0-321-12521-5.

11. Nik Boyd. EDUCE: A Pattern Language of Language Patterns. http://educery.com/educe/patterns/educe-overview.html.

Appendix A. Trace Card Templates