Wait, why did we decide this?

Have you ever been mid-project (or joined a new one) and thought:

• Why is this protocol structured this way?
• Why does the user need to jump through all these hoops to set up the device?
• Who made this (wacky?) decision and why?

Without context, even the best-intentioned decisions can feel baffling over time. This is where Architecture Decision Records (ADRs) come in handy.

An ADR is a lightweight document that captures why a decision was made, along with the context and trade-offs involved.

Instead of guessing or piecing together Slack threads six months later, you’ll have a clear record that says:

• Here’s what we decided
• Here’s why we decided it
• Here’s what we considered, and here’s what we rejected

The idea is simple: document key decisions as you make them. It’s not about documenting everything, but focusing on the ones that make you stop and ask: “Why did we do it this way?”

For example, using ADRs, we could answer questions like:

• Why did we choose this data flow for the app?
• Why are these hoops part of the setup process?
• Why does this protocol require three separate requests?

The ADR format is straightforward:

1. Title: The decision name (e.g., “Protocol X Setup Design”).

2. Context: The problem or situation we faced.

3. Decision: What we chose to do and why.

4. Consequences: Positive and negative outcomes of the decision.

I know this isn't specific to Bluetooth, but it is something I've found helpful to do during the design of Bluetooth products.