# Design Rationale Design Rationale (DR) is the documentation of the reasons behind design decisions—not just *what* was designed, but *why* those choices were made and what alternatives were considered. Capturing rationale helps future maintainers understand the context of decisions, prevents re-debating settled issues, and preserves institutional knowledge. [[Thomas P. Moran]] and others at Xerox PARC pioneered DR research in the 1980s-90s. The challenge with design rationale is the overhead of capturing it. Rich DR systems (like IBIS or QOC) require significant effort, leading to low adoption. Modern approaches integrate rationale capture into existing workflows: git commit messages, architectural decision records (ADRs), and inline code comments. The key insight is that *some* rationale captured informally beats comprehensive rationale that's never written. ## Why Capture Design Rationale? | Benefit | Description | |---------|-------------| | **Maintenance** | Understand why code/design is the way it is | | **Onboarding** | New team members learn context faster | | **Avoid repetition** | Don't re-debate settled decisions | | **Quality** | Forces explicit consideration of alternatives | | **Communication** | Share reasoning across teams/time | | **Compliance** | Document decisions for audits/reviews | ## Notations and Methods | Method | Description | |--------|-------------| | **IBIS** | Issue-Based Information System (questions, positions, arguments) | | **QOC** | Questions, Options, Criteria framework | | **DRL** | Decision Representation Language | | **ADR** | Architectural Decision Records (lightweight) | | **RFC** | Request for Comments documents | | **Commit messages** | Informal rationale in version control | ## IBIS Structure Issue-Based Information System (Kunz & Rittel, 1970): ``` ┌─────────────┐ │ Issue │ "How should we handle auth?" │ (Question) │ └──────┬──────┘ │ ┌──────────┼──────────┐ ▼ ▼ ▼ ┌────────┐ ┌────────┐ ┌────────┐ │Position│ │Position│ │Position│ "Use JWT" / "Use sessions" / "Use OAuth" │ A │ │ B │ │ C │ └───┬────┘ └───┬────┘ └───┬────┘ │ │ │ ▼ ▼ ▼ ┌────────┐ ┌────────┐ ┌────────┐ │Argument│ │Argument│ │Argument│ Pros/cons of each │(Pro/Con)│ │(Pro/Con)│ │(Pro/Con)│ └────────┘ └────────┘ └────────┘ ``` ## Architectural Decision Record (ADR) Modern lightweight format: ```markdown # ADR 001: Use PostgreSQL for primary database ## Status Accepted ## Context We need a relational database for transactional data. ## Decision Use PostgreSQL. ## Alternatives Considered - MySQL: Less feature-rich - MongoDB: Wrong paradigm for our data ## Consequences - Team needs PostgreSQL expertise - Can use advanced features (JSONB, etc.) ``` ## QOC Framework Questions, Options, Criteria: | Element | Example | |---------|---------| | **Question** | Which frontend framework should we use? | | **Options** | React, Vue, Svelte | | **Criteria** | Team expertise, performance, ecosystem | | **Assessment** | Rate each option against criteria | ## Challenges - **Overhead**: Capturing rationale takes time - **Maintenance**: Rationale can become outdated - **Granularity**: How much detail is enough? - **Retrieval**: Finding relevant rationale later - **Culture**: Teams must value documentation ## Best Practices 1. **Capture at decision time**: Easier than reconstructing later 2. **Use lightweight formats**: ADRs over complex systems 3. **Integrate into workflow**: Git, wikis, issue trackers 4. **Focus on significant decisions**: Don't document everything 5. **Include alternatives**: What was *not* chosen and why ## References - https://en.wikipedia.org/wiki/Design_rationale - https://adr.github.io (ADR resources) - Moran, T. & Carroll, J. (1996). *Design Rationale: Concepts, Techniques, and Use* ## Related - [[Thomas P. Moran]] - [[Decision Making]]