## What Are TDRs? A **Technical Decision Record** (TDR) is a lightweight document that captures the context, options considered, and rationale behind a significant technical decision. Unlike ADRs (Architecture Decision Records), TDRs cover decisions at every level — from library choices to API design patterns to deployment strategies. ### Why They Matter Six months from now, someone (probably you) will ask: *"Why did we choose DynamoDB over PostgreSQL for this service?"* Without a TDR, the answer lives in: - Slack messages that expired - Meeting notes nobody can find - The memory of someone who left the company ### The Template I use a dead-simple format: ```markdown # TDR-042: Use SQS over Kafka for order processing **Status:** Accepted **Date:** 2026-01-15 **Deciders:** John, Sarah, Mike ## Context We need a message queue for async order processing. Expected throughput: 500 msgs/sec peak. ## Options Considered 1. Amazon SQS — managed, simple, pay-per-use 2. Apache Kafka — high throughput, event replay 3. RabbitMQ — flexible routing, self-managed ## Decision SQS. Our throughput doesn't justify Kafka's operational overhead. We don't need event replay for this use case. ## Consequences - No message replay capability - Limited to 256KB message size - Simpler ops, lower cost ``` ### Tips for Adoption 1. **Make it frictionless** — a Git-tracked markdown file, not a Confluence page nobody maintains 2. **Record the *why*, not just the *what*** — the decision is obvious in hindsight; the reasoning isn't 3. **Include rejected options** — knowing what you *didn't* choose is as valuable as knowing what you did 4. **Keep them immutable** — supersede, don't edit. History matters.
