Decision Logs

Why this matters

As a Data Architect, you make choices that shape data platforms for years: storage formats, warehouse vs. lakehouse, partitioning, privacy controls, SLAs, and tooling. Decision logs (often called Architecture Decision Records, ADRs) make these choices explicit, reviewable, and explainable. They reduce rework, align stakeholders, speed onboarding, and protect context when teams change.

• Real tasks you will face: choosing a warehouse vendor; setting modeling standards; approving retention for PII; picking orchestration tools; migrating from batch to streaming.
• Decision logs help you avoid: repeated debates, lost rationale, unapproved changes, and shadow decisions.

Concept explained simply

A decision log is a short note that records a significant choice, why it was made, and what it implies. Think of it as the minimum viable memory of your architecture.

Mental model

Picture a map legend. Each symbol (decision) is small, but together, they explain the whole map (your architecture). You don’t write a novel; you add clear symbols:

• Context: the problem and constraints
• Options: what you considered
• Decision: what you chose
• Rationale: why this option won
• Consequences: trade-offs and follow-up actions
• Status and dates: lifecycle tracking

A lightweight template you can copy

Use this concise template. Keep it consistent across your team.

Title: <short, action-oriented>
Status: Proposed | Accepted | Deprecated | Superseded
Date: YYYY-MM-DD
Owner: <name/role>
Review Date: YYYY-MM-DD (if assumptions exist)

Context:
- <problem and constraints>

Options Considered:
- Option A: <1 line>
- Option B: <1 line>

Decision:
- We will <what you will do>.

Rationale:
- <key reasons and trade-offs>

Consequences:
- Positive: <benefit>
- Negative: <cost/risk>
- Actions: <follow-ups>

Related:
- <IDs/titles of related decisions>

Worked examples

1) Choosing a cloud data warehouse

Title: Adopt Snowflake as primary analytical warehouse
Status: Accepted
Date: 2026-01-10
Owner: Data Architect

Context:
- Need scalable SQL analytics for BI and data science.
- Teams require near-elastic compute with simple ops.

Options Considered:
- Snowflake; BigQuery; Redshift

Decision:
- We will adopt Snowflake for analytical workloads.

Rationale:
- Strong separation of storage/compute; easy workload isolation; team familiarity.

Consequences:
- Positive: Elastic virtual warehouses reduce contention.
- Negative: Cost variability under bursty loads; need cost guardrails.
- Actions: Implement warehouse auto-suspend; monthly cost reviews; tagging policy.

Related:
- Cost governance policy

2) Data modeling standard

Title: Use star schemas for BI marts
Status: Accepted
Date: 2026-01-12
Owner: Principal Data Modeler

Context:
- BI team needs predictable, fast dashboards across domains.

Options Considered:
- Star schema; Data Vault; Wide tables

Decision:
- We will model BI marts using star schemas with conformed dimensions.

Rationale:
- Suits BI access patterns; simpler training; consistent semantics.

Consequences:
- Positive: Faster dashboard dev; better join performance.
- Negative: ETL complexity for conformance; training needed for slowly changing dimensions.
- Actions: Create dimension naming guide; SCD policy v1.

Related:
- Semantic layer standards

3) Handling PII in logs

Title: Mask PII at ingestion for app logs
Status: Proposed
Date: 2026-01-15
Owner: Security Architect
Review Date: 2026-02-15

Context:
- Regulatory exposure from raw app logs with emails/phones.

Options Considered:
- Mask at source; Mask in lake; Tokenize downstream

Decision:
- We will mask emails and phone numbers at ingestion using deterministic hashing.

Rationale:
- Reduces blast radius; preserves join capability for investigations.

Consequences:
- Positive: Lower compliance risk.
- Negative: Some analytics need reversible lookup via secure vault.
- Actions: Implement hash function; build vault-backed re-identification with audit.

Related:
- Data retention policy

How to create strong decision logs (step-by-step)

1. Trigger: Notice a decision with impact on cost, risk, operations, or standards.
2. Draft: Fill Context, Options, Decision, Rationale, Consequences. Keep it under 10–15 lines.
3. Review: Share with key roles (e.g., Security, Platform, BI). Invite dissent.
4. Status: Mark Proposed → Accepted (or deprecated/superseded if needed).
5. Publish: Save in a shared, searchable location. Use consistent naming.
6. Maintain: Add review dates if assumptions exist; link related decisions.

Communication and maintenance

• Keep it short: the log is a pointer to context, not a full design doc.
• Discuss asynchronously: collect comments before meetings; meetings become approve-or-adjust.
• Capture dissent: note concerns and how you’ll monitor them.
• Lifecycle: supersede old decisions rather than editing history; keep traceability.

1) Restate the problem in one line.
2) Present options and evaluation criteria.
3) Propose the decision; ask for risks you might be underweighting.
4) Confirm owner, status, follow-ups, and review date.
5) Record dissent and monitoring plan.

Exercises (do these now)

These mirror the exercises below. Aim for concise, unambiguous wording.

Exercise 1 — Write a decision log: Warehouse choice

Scenario: Your analytics team struggles with query contention and unpredictable performance in the current on-prem database. You piloted a cloud warehouse with elastic compute. Draft a decision log using the template. Keep it under 12 lines.

Exercise 2 — Rewrite a chat thread into a clean log

Scenario: A Slack debate argued about daily vs hourly partitions for clickstream. Concerns: cost of many small files; freshness for product analytics. Convert this into a decision log (title, context, options, decision, rationale, consequences, owner).

Exercise checklist

• Clear, active-voice decision
• Options and criteria present
• Trade-offs and actions listed
• Status, date, owner included

Common mistakes and self-check

• Writing essays: If your log exceeds ~15 lines, link to or reference a design doc instead and keep the log concise.
• No options: If you list only one option, you didn’t decide—you assumed. Add at least one alternative.
• Hiding trade-offs: Name the downsides to build trust and guide mitigation.
• Missing status: Without Proposed/Accepted/Deprecated, readers can’t act on it.
• Stale decisions: Add review dates when assumptions exist (cost, performance, volume).

In one sentence: what did we choose and why now?
What would make us change this decision?
Which metric will tell us if this was wrong?
Do we have named actions and an owner?

Practical projects

• Create a decision log set for a greenfield analytics stack (storage, compute, orchestration, modeling standard, governance). Keep each entry under 10 lines.
• Backfill history: Convert the last three major architecture choices your team made into decision logs. Note any missing context and add review dates.
• Run a monthly “decision review”: pick one log, report metrics against assumptions, and update status or actions.

Learning path

• Before this: Basic architecture documentation; understanding of your platform’s components and constraints.
• This subskill: Learn to capture, communicate, and maintain architecture decisions.
• After this: Standards governance, architecture roadmapping, and risk assessment practices.

Who this is for

• Data Architects and Platform Leads who own technical direction
• Senior Data/Analytics Engineers influencing architecture
• Tech Leads who need crisp decision traceability

Prerequisites

• Familiarity with your data stack (warehouse/lake, orchestration, security basics)
• Ability to outline pros/cons and evaluate trade-offs
• Basic writing clarity (active voice, short sentences)

Next steps

• Adopt the template team-wide and make it the default for significant choices.
• Schedule a monthly 30-minute decision review for updates and clean-up.
• Create tags (e.g., cost, risk, security, performance) for quick filtering.

Quick Test

The quick test below is available to everyone. If you sign in, your progress will be saved automatically.

Mini challenge

Pick one pending decision in your current project. Draft a decision log in under 10 minutes. Share it with two stakeholders and ask them to highlight one risk you underweighted. Update the log with actions and a review date.