Trace Cards

Abstract

This paper introduces a 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¹ during software development are also offered.

Introduction

Having adopted an agile approach to continuously delivering value, software developers also need simple ways to capture and share knowledge about the problems they are solving. Large (4″ x 6″) index cards provide a convenient form factor for capturing and sharing such knowledge. Index cards are convenient from several standpoints:

They are (literally) handy.
They are easy to use and share.
They encourage brevity and simplicity (focus).
They are cheap, portable, readily available, and familiar.

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, while CRC cards¹ are solution oriented, 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.

Precedents 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

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 UML Unified Modeling Language.² 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

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.

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.⁴

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

Policy Cards

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:

to align software solution requirements with business policies,
to trace software solution purposes back to business policies,
as touchstones for prioritizing software solution features,
throughout the various requirements levels.

A policy card should always capture the following information:

A benefit description describes the benefit(s) conferred by the instantiation.
A quality instantiation is a simple noun phrase composed of two parts:
1. a descriptive adjective derived from the quality / value theme, and
2. a common noun phrase that identifies a subject of concern under the identified theme.

A policy card may also exhibit one of two organizational variations: organized by theme and organized by subject. See the provided example cards for what this might look like in practice. 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.⁵

Intelligence Cards

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. See the provided example cards for what this might look like in practice.

Together, they can be used:

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 shows a general quality area or issue of interest to a kind of stakeholder.
A quality concern subject shows 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 shows a kind of stakeholder concern about the focus quality.

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

A stakeholder objective shows the intended quality objective of the identified stakeholder.
A stakeholder goal / target shows 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 shows 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 shows a characteristic needed to answer a question of concern.
Each listed quality condition shows a relevant relation between measurements.
Each listed source / instrument shows the origin of the measurement and derivation of the condition.

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 shows a condition expected by the primary actor when the use case completes normally.
Each listed stakeholder interest shows a condition as a quality valued by the associated stakeholder.
A scenario trigger shows a condition the trigger actor effects to initiate the use case.
Each listed scenario step shows the action of the associated step actor that moves the scenario forward.

A face card may also capture preconditions and postconditions:

Each listed precondition shows a condition ensured by a guarantor prior to the inception of the use case.
Each listed minimal guarantee shows a condition always ensured as result for an intended recipient.
Each listed success guarantee shows a success condition ensured as result for an intended recipient.

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. See the provided example face cards for what this might look like in practice.

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.

Further Considerations

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 understand 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 (just enough) time discussing quality expectations (at least somewhat), 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.

Extending Responsibility-Driven Design

Historically, the usage of CRC cards¹ in the practice of responsibility-driven design¹² 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. Also, and especially in the context of responsibility-driven designs, each object plays some role(s) in collaboration with other objects. And so, each object knows who it is, metaphorically. Also, their knowledge is situated (where located relative to other collaborators), as is their behavior (when applicable relative to prevailing conditions).

Every object

knows	some information (with structure)	what, where
does	some behaviors (with functions)	how, when
ensures	some qualities (with conditions)	why
is	some concept (with a role and relations)	“who“

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. 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

Knowledge	Sources	Traceability Intent
Policy Cards: quality concerns, benefits, value	Governors: board + officers, vision, mission, values	traces back to business policy statements: vision, mission, values
Intelligence Cards: concerns, goals, metrics, measurement linkage	Requestors: activity managers, other stakeholders, objectives, goals	traces business intelligence requirements back to business policies and priorities
Face Cards: goals, interests, expectations, obligations, interactions	Expectors: activity participants, users and other stakeholders, business contracts, user stories	traces business activities and activity improvement goals back to business policies and priorities
CRC Cards: responsibilities for: quality, behavior, knowledge	Developers: design sessions and decisions	traces solution designs back to business activities and business intelligence requirements

References

Kent Beck, Ward Cunningham. A Laboratory for Teaching Object-Oriented Thinking. OOPSLA 1989 Conference Proceedings. ACM SIGPLAN Notices 24(10), 1989.
Object Management Group. UML™ Resource Page. http://www.uml.org/.
Alistair Cockburn. Writing Effective Use Cases. Addison-Wesley Publishing, Inc., 2000. ISBN 0-201-702258.
Nik Boyd. A Conceptual Model for Software Requirements. educery.dev
Nik Boyd. Quality Alignment and Quality Inventories. educery.dev
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.
Scott Whitmire. Object-Oriented Design Measurement. John Wiley & Sons, Inc., 1997. ISBN 0-471-13417-1.
Ron Jeffries, Ann Anderson, Chet Hendrickson, Kent Beck. Extreme Programming Installed. Addison-Wesley Publishing, Inc., 2001. ISBN 0-201-70842-6.
Kent Beck, Extreme Programming Explained: Embrace Change. Addison-Wesley Publishing, Inc., 2000. ISBN 0-201-61641-6.
Eric Evans. Domain-Driven Design: Tackling Complexity in the Heart of Software. Addison-Wesley Publishing, Inc., 2003. ISBN 0-321-12521-5.
Nik Boyd. EDUCE: A Pattern Language of Language Patterns. educery.dev
Rebecca Wirfs-Brock, Alan McKean. Object Design: Roles, Responsibilities, and Collaborations. Addison-Wesley, 2003. ISBN 0-201-37943-0.