Design Rationale
The documentation of the reasons behind design decisions, capturing not just what was designed but why those choices were made and what alternatives were considered.
Also known as: Design Rationale Documentation, DR
Category: Software Development
Tags: design, documentation, decision-making, software-development, knowledge-management
Explanation
Design Rationale (DR) is the practice of documenting the reasoning behind design decisions. It goes beyond recording what was designed to capture why specific choices were made, what alternatives were considered, and what trade-offs were accepted. This documentation helps future maintainers understand the context of decisions, prevents teams from re-debating settled issues, and preserves institutional knowledge that would otherwise be lost over time.
The concept was pioneered by Thomas P. Moran and others at Xerox PARC in the 1980s-90s, who developed structured approaches like IBIS (Issue-Based Information System) and QOC (Questions, Options, Criteria). IBIS structures discussions around issues (questions), positions (potential answers), and arguments (pros and cons). QOC explicitly maps questions to options and evaluates them against defined criteria.
The primary challenge with design rationale is the overhead of capturing it. Rich DR systems require significant effort, which often leads to low adoption. Modern approaches address this by integrating rationale capture into existing workflows: git commit messages, Architectural Decision Records (ADRs), inline code comments, and RFCs. The key insight is that some rationale captured informally is far more valuable than comprehensive rationale that never gets written.
Benefits of capturing design rationale include: easier maintenance (understanding why code exists as it does), faster onboarding (new team members learn context quickly), avoiding repetition (no re-debating settled decisions), improved quality (forces explicit consideration of alternatives), better communication (shares reasoning across teams and time), and compliance (documents decisions for audits and reviews).
Best practices include: capturing rationale at decision time rather than reconstructing later, using lightweight formats like ADRs over complex systems, integrating into existing workflows, focusing on significant decisions rather than documenting everything, and always including the alternatives that were not chosen and why.
Related Concepts
← Back to all concepts