Explicit Capture Tools for Design Rationale

Core Concepts

IBIS: The Ancestor of Explicit Rationale Capture

The design rationale capture field has a long pedigree. Issue-Based Information Systems (IBIS) were developed by Werner Kunz and Horst Rittel in the 1960s–1970s as a formal approach to structuring "wicked problems" — complex, ill-defined problems involving multiple stakeholders. The core structure is deliberately simple: issues (questions that arise), positions (possible answers), and arguments (reasons that support or oppose positions). These nodes connect through support and opposition relations, forming an explicit map of the reasoning behind decisions.

IBIS wasn't a tool for documenting after the fact. Its purpose was to make the deliberation itself legible — to treat the reasoning behind a decision as a first-class artifact, not a footnote.

Fig 1

gIBIS and Compendium: Tooling the Notation

The notation stayed on paper until 1987, when gIBIS (graphical IBIS) introduced a computational implementation. By giving teams a graphical interface to visualize issue-position-argument networks, gIBIS aimed to reduce the friction of capture — the hypothesis being that if the tool made the notation easier to manipulate, adoption would follow. The tool spawned successors: itIBIS (a text-based variant) and eventually Compendium, developed in 1993.

Compendium brought IBIS-style notation to a wider audience, applied in both industry and academic settings. Each tool iteration tried to improve on usability. None solved the underlying tension.

QOC: Design-Space Analysis as a Coproduct

Questions, Options, and Criteria (QOC), developed by MacLean, Young, Bellotti, and Moran, takes a different stance. Where IBIS frames deliberation as argumentation, QOC frames it as design-space analysis:

• Questions identify key design issues.
• Options propose possible answers.
• Criteria establish how to assess and compare those options.

The key architectural difference from IBIS: QOC is explicitly constructed alongside the artifact being designed, as a coproduct of the design process rather than a post-hoc record. This is not a minor distinction. It changes when capture happens, who does it, and what it costs.

DRL: Greater Expressiveness, Greater Weight

The Decision Representation Language (DRL), developed by Jintae Lee and Kum-Yew Lai, pushed further. DRL represents decision problems, alternatives, goals, claims, and groups — capturing the qualitative structure of decision-making. Lee and Lai argued that DRL was more expressive than IBIS or QOC, explicitly supporting dependency management, plausibility assessment, viewpoint tracking, and precedent handling.

SEURAT (Software Engineering Using RATionale) was built on DRL, using a language called RATSpeak and introducing an Argument Ontology — a hierarchy of argument types that integrates functional and non-functional requirements into the argument structure.

More expressiveness is not always better. DRL and SEURAT represent the upper bound of what you can encode — and that comprehensiveness is precisely what made them impractical.

ADRs: The Pragmatic Retreat

Architecture Decision Records (ADRs) emerged as a deliberate simplification. An ADR documents the context, the decision made, its status, and its consequences — no formal node types, no argument ontology, no dedicated tooling required. A markdown file in the repository is sufficient.

Empirical measurement of GitHub repositories tells a sobering story: approximately 50% of repositories using ADRs contain only one to five records total. Even where ADRs are used, they remain a practice conducted by a minority of projects. The dominant template is Michael Nygrad's. The dominant outcome is thin usage.

---

Compare & Contrast

Method	Structure	Capture moment	Expressiveness	Adoption cost
IBIS	Issues / Positions / Arguments	During or after deliberation	Moderate	High (notation is unfamiliar)
gIBIS / Compendium	IBIS with graphical tooling	During deliberation	Moderate	High (tooling friction)
QOC	Questions / Options / Criteria	Alongside design (coproduct)	Moderate	High (requires discipline)
DRL / SEURAT	Decision problems / Alternatives / Goals / Claims	During or after	Highest	Very high (full ontology)
ADRs	Context / Decision / Status / Consequences	After decision	Low	Low (markdown, no tooling)

The central axis for selection is not "which method captures the most?" but "which method will actually be used?"

---

Annotated Case Study

The IBIS Lifecycle: A Pattern Repeated Across Three Decades

The trajectory of IBIS-family tools illustrates a pattern that repeats across the entire design rationale field.

Phase 1 — Notation invented. Kunz and Rittel develop IBIS to handle wicked problems. The notation is intellectually sound and directly addresses a real gap: the invisibility of deliberation.

Phase 2 — Tool built to lower friction. gIBIS (1987) graphically implements IBIS. The hypothesis: if it's easier to draw, teams will draw it. Research on its use documents that initial enthusiastic users encountered difficulty building their first representations, finding the rhetorical moves unwieldy.

Phase 3 — Tool refined, context broadened. Compendium (1993) expands the audience to BPR teams and academic settings. More polished, more accessible. Still a specialized tool requiring dedicated practice to use.

Phase 4 — Abandoned outside specialized contexts. Despite three decades of iteration, IBIS-family tools did not become standard engineering practice.

What the annotation reveals: The problem was not the notation's correctness or the tools' quality. The problem was structural. Capture imposes overhead at the moment of design, and the moment of design is precisely when teams have the least capacity to add process. Each tool generation assumed the barrier was interface friction. The actual barrier was timing and workflow disruption.

The same pattern, compressed, plays out with ADRs. Simpler structure, no dedicated tooling, markdown in the repo — and still, most repositories using ADRs contain fewer than five records. The simplification reduced cost but did not eliminate the structural problem.

---

Common Misconceptions

"If the tool is good enough, teams will adopt it."

The IBIS lineage from gIBIS through Compendium represents three decades of tooling investment. Research consistently documents that initial enthusiastic users abandoned rationale documentation efforts not because the tools were bad, but because information capture hindered design activities by imposing overhead and disrupting natural workflow. Tool quality is a necessary but nowhere near sufficient condition.

"ADRs solve what formal DR methods couldn't."

ADRs are a pragmatic reduction, not a solution. They lower cost by reducing expressiveness. They do not eliminate the timing problem — decisions still need to be recorded at or near the moment they are made, which is still the moment of highest pressure. The empirical evidence on ADR repositories confirms this: the adoption gap persists even with maximum simplification.

"Practitioners don't document rationale because they don't see its value."

Research distinguishes between recognizing theoretical importance and being able to act on it consistently. Practitioners understand that documenting design rationale would preserve knowledge for maintenance and refactoring. They still don't do it consistently. The barrier is not perceived value — it is the structural mismatch between when documentation is needed (now, during active design) and when it can be afforded (later, if ever).

"Design rationale documentation is for mature teams with stable processes."

Design rationale documentation emerged as a formal discipline specifically because the teams that most need preserved reasoning — teams in active development under pressure — are the least able to produce it. IEEE 1471 standards incorporate rationale documentation as essential. Complete documentation is acknowledged as too costly to maintain systematically. The gap exists regardless of team maturity.

---

Boundary Conditions

When IBIS or QOC add value despite their cost

Formal DR methods earn their overhead when the design process is itself the deliverable, or when a structured deliberation needs to be auditable. If you are facilitating an architectural review that will be scrutinized later, gIBIS or Compendium can make the deliberation legible in ways that notes cannot. The cost is justified by the stakes and the need for an explicit record of the reasoning path.

When ADRs are insufficient

ADRs record context, decision, and consequences. They do not model the structure of the deliberation — the options not chosen, the criteria applied, the arguments made. When that missing structure matters (e.g., a team inherits a system and needs to understand why Option B was rejected, not just that Option A was chosen), ADRs leave a gap that can only be filled by the people who were present.

When no formal method is appropriate

Complete design rationale documentation is acknowledged as too costly for systematic industrial use. This is not a failure of discipline or tooling — it is a structural fact about the economics of design work. Attempting to apply formal DR methods to every decision is worse than selective application: it creates a compliance burden that discredits the practice and leads to abandonment.

The expressiveness ceiling

DRL and SEURAT represent the maximum expressiveness available in the formal DR design space. If you need to track dependencies between decisions, assess plausibility, and record viewpoints across stakeholder groups — and if the team can sustain the adoption cost — DRL-family tools are the right instrument. In practice, the teams capable of sustaining that cost are rare, and the contexts that demand it (regulated industries, safety-critical systems, long-lived platforms with governance requirements) are the only ones where the overhead clears the bar.

---

Active Exercise

Method Selection Under Real Constraints

Work through the following two scenarios. For each, select a DR method and justify the selection using the trade-off dimensions from the Compare & Contrast section.

Scenario A: Your team is four engineers, pre-Series A, two months from a hard deadline. You are making three significant architectural choices that will be difficult to reverse. Your engineering manager has asked for "some documentation" of the decisions. You have no existing DR practice.

Scenario B: You are the staff engineer on a platform team at a mid-size company. A major refactor is coming that will affect decisions made over the previous two years. No rationale was documented at the time. You have discovered that several design choices are now unexplained and the engineers who made them have left. You have been asked to establish a forward-looking DR practice so this doesn't happen again.

For each scenario, answer:

1. Which method do you recommend, and why?
2. What is the realistic adoption risk, and how do you mitigate it?
3. What would indicate, after 90 days, that the method is working?
4. At what point would you recommend switching to a different method — or stopping entirely?

There is no single correct answer. The exercise is to reason explicitly through the trade-offs, not to arrive at a canonical choice.