Copyright 2003, 2014 Nikolas S. Boyd. Permission is granted to copy this document provided this copyright statement is retained in all copies.
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.
Software developers need simple ways to capture and share knowledge. Large (4" x 6") index cards provide a convenient form factor for capturing and sharing knowledge. Index cards are convenient from several standpoints:
For these reasons, index cards can facilitate some of the most difficult aspects of software development, including not only solution design, but also problem definition. Just so, trace cards are primarily problem oriented. Trace cards offer a convenient and efficient way to capture and share knowledge about business policies, business intelligence needs, and business activities. They offer a way to keep object-oriented software designs aligned with business policies and priorities.
During the late 1980s, Ward Cunningham and Kent Beck introduced the use of CRC cards1 (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,10 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.
How should knowledge about business problems be captured? What kind of residue should remain and be maintained after solution development? These questions often arise during software development projects. Most modern human interfaces are graphical, and so require graphical designs. Also, since the early 1980s, graphical notations have become a popular way to visualize other aspects of software.
Some methodologists have offered elaborate graphical notations for capturing knowledge about business elements and activities, e.g., the Unified Modeling Language2 (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. 11 There are several aspects of this work that are inspired in part by EDUCE.
Success is rarely accidental. It must usually be planned. This is especially true for software development. Software is a conceptual artifact. Software developers need conceptual leverage, techniques that make tackling the inherent complexity of software solution design tractable. First and foremost, software developers need to ensure that their work products align with the policies and improve the activities of a business.
Software solutions support and improve business activities. Business activities are directed by business policies. Business intelligence provides the management community with data critical to the guidance of business activities and the maintenance of their alignment with business policies.
Trace cards extend conceptual thinking beyond objects into their business origins. They provide ways to capture and share knowledge about business policies (vision and mission), business intelligence (qualities and quantities), and business activities (workflows and solution usage). They also help establish and maintain alignment and traceability across requirements levels.
Solution designs are usually impacted by various forces and constraints outside of the control of a solution designer. Engineers evaluate and attempt to balance the known forces based on their known or discovered effects. To properly evaluate and balance a set of forces, an engineer needs to know not only what these forces are, but also how they relate to each other. Software designers need to know not only what to accomplish and how, but also why. Trace cards provide answers to some of these questions.
Explicitly identifying the nature and level of goals can help us to align technology development with business objectives. In Writing Effective Use Cases,3 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.4
Business policies establish the ends, means, and central values of a business. These policies traditionally appear in business vision, mission, and value statements. These core business documents originate in the corporate governance community, especially the board of directors, the corporate officers, and the management team.
Policy cards generally derive their focus from business governance policy statements: vision, mission, values. Policy cards provide a way to capture and organize selected business policies on index cards. They can be used:
A policy card should always capture the following information:
A benefit description describes the benefit(s) conferred by the instantiation.
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),
When policy concerns are organized by subject (see Card Template 2),
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.5
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
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
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)
| Card 4. Drum Storage Allocation Qualities (Internal)
Business intelligence offers management the information needed to guide the business in the directions established by business policies. Business intelligence regards the various business quality concerns, especially the (quantitative) measurement of the relevant business products and activities.
Intelligence cards are generally paired: a quality card with a quantity card. A quality card collects knowledge about a single business quality concern, while the corresponding quantity card collects details about the measurements related to that quality concern. Together, they can be used:
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 card (see Card Template 3) captures the following additional information:
A quantity card (see Card Template 4) captures the following additional information:
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
These quality constraints may then be quantified and made measurable.
Card 6. Drum Storage Conditions and Measures
As well, the EPA defines the following safety criteria.
Card 7. Drum Storage Regulations
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 Cases3 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 face card may also capture preconditions and postconditions:
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.
An ECO depot manager must monitor the depot and ensure its safety. The system must help each depot manager fulfill this responsibility by reportng the depot status in detail.
Card 8. Depot Monitoring
To ensure depot safety, the system needs to know which hazard types each storage building has been licensed to store. To minimize depot vulnerability, the system needs to know which buildings are neighbors. Thus, the system needs a map of the depot and a storage license inventory. A depot manager is responsible for supplying this information.
Card 9. Depot Map Maintenance
To ensure depot safety, a depot manager must supply the system with accurate information about the depot buildings, including their locations and physical dimensions.
Card 10. Depot Building Additions
From a certain perspective, the prevailing state of software development practice has inverted priorities. Typically, we rush (or are rushed) to implement solutions before we sufficiently understanding the problems we're being asked to solve. Stakeholders tacitly assume that software solutions will improve the quality of their lives and business activities. But, such benefits still elude our collective grasp far too often. Without giving quality due consideration, without spending significant time discussing quality expectations explicitly and systematically, the achievement of a sufficient solution that satisfies its requirements (satisficing) will continue to be accidental and haphazard rather than intentional and sure. The "rubber meets the road" where requirements meet designs.
Historically, the practice of responsibility-driven design with CRC cards has focused primarily on knowledge (noun phrases) and behavior (verb phrases) to the virtual exclusion of qualities (as expressed by descriptive adjectives). The absence of quality responsibilities can usually be traced back to the absence of quality considerations in the original requirements. Quality requirements often receive little or no consideration during requirements gathering, especially in comparison with the emphasis often placed on form and function.
But, the consideration of object responsibilities should properly include qualities in addition to knowledge and behavior. Conceptually, we can understand qualities as expressive of the dimension (and states) of being. So, objects have and ensure qualities in addition to having knowledge and doing behaviors. Objects should know why in addition to what and how. Every object
In practice, object-oriented designs entail strong contracts between servers and their clients. So, a server object imposes responsibilities (especially for quality) on its clients as preconditions to the proper usage of its services. Likewise, a server object offers quality guarantees to its clients (as postconditions and invariants). Method preconditions (ensured by clients), method postconditions (ensured by servers), invariants (ensured by servers), constraints, and qualified class names all offer the potential for consideration with respect to quality requirements.
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),9 and can also serve as a natural adjunct to language focused approaches like domain-driven design (DDD).10
|Card Type||Knowledge||Sources||Traceability Intent|
|Policy Card||quality concerns, benefits (value)||governors: board + officers, vision, mission, values||tied to business policy statements: vision, mission, values|
|Intelligence Cards||concerns, goals, metrics, measurement linkage||requestors: activity managers, other stakeholders, objectives, goals||ties business intelligence requirements back to business policies and priorities|
|Face Card||goals, interests, expectations,
|expectors: activity participants, users and other stakeholders, business contracts, user stories||ties business activities and activity improvement goals back to business policies and priorities|
|CRC Card||responsibilities for: quality, behavior, knowledge||developers: design sessions and decisions||ties solution designs back to business activities and business intelligence requirements|
| Template 1.
Theme-Oriented Policy Card
| Template 2.
Subject-Oriented Policy Card
| Template 3.
Intelligence Quality Card
| Template 4.
Intelligence Quantity Card
| Template 5. Face