Team Knowledge
How to build a decision log — a practical guide for teams and organizations who want a permanent, searchable record of significant decisions that makes the reasoning behind current practices visible and prevents repeated debating of already-resolved questions.
Every organization makes hundreds of significant decisions each year. Most of those decisions leave no permanent record beyond the people who made them and the outcomes they produced.
The problems this creates are specific and recurring:
The "why do we do it this way?" problem: A new employee, or an employee who wasn't in the room, asks why a process, policy, or system is the way it is. The answer — if one exists — comes from whoever remembers the meeting. If that person has left, or if memory has faded, the answer is "I don't know; it's just how it's always been." Decisions look arbitrary when their reasoning isn't preserved.
The "we already decided this" problem: A team debates a question that was already resolved months or years ago. They reach the same conclusion (wasting time) or a different one (creating inconsistency) — all because no one knew the prior decision existed. This problem is most common at the boundaries between teams and after personnel changes.
The "what were we thinking?" problem: Looking back at past decisions, it's often unclear why they were made — especially decisions that look wrong today. Without the original context (the constraints, the alternatives, the reasoning), it's impossible to tell whether the decision should be revisited or whether it was correct given the constraints at the time.
A decision log solves all three problems by creating a permanent, searchable record of what was decided and why.
Not every decision belongs in the decision log. The decision log is for decisions that:
Will be wondered about later. If someone is likely to ask "why do we do it this way?" six months from now, the reasoning belongs in the decision log.
Affect how the team works or how systems behave. Choices about process, architecture, vendor relationships, policies, and org design are candidates. Operational decisions within an established process ("we handled this customer case by applying the standard refund policy") typically are not.
Were genuinely debated or could have gone another way. If the decision was obvious and no alternatives were considered, the rationale is probably self-evident. If alternatives were considered and rejected, the reasoning for the rejection belongs in the log.
Involve significant trade-offs. Decisions where something valuable was given up to gain something else — speed over robustness, simplicity over flexibility, cost over capability — are worth documenting because the trade-off reasoning may need to be revisited as conditions change.
In practice: a few decisions per week in an active organization, not dozens. The decision log is a curated record, not a meeting transcript. The act of deciding "does this go in the log?" is itself a forcing function for explicit reasoning.
A decision log entry that will be useful when referenced months or years later:
Decision ID and title: A unique identifier (D-001, D-002, etc.) and a short, specific title. "Switch to asynchronous customer notifications" is a good title. "Notification system change" is not.
Date: When the decision was made.
Decision-maker(s): Who made the decision. Not who was consulted — who actually decided. In organizations with clear authority, this is one person. In collaborative teams, it may be a named group.
The decision: A clear, specific statement of what was decided. This should be unambiguous enough that someone who reads it without attending the meeting can understand what the team is committing to.
Context: The background that shaped the decision. What was the situation at the time? What constraint, event, or condition made this decision necessary? This is the most important field for future readers — it's the difference between "we did this for a reason" and "we did this because of this specific, understandable reason."
Alternatives considered: The options that were evaluated and not chosen, with a brief explanation of why. This prevents future debate from re-opening alternatives that were already explored.
Why this choice: The reasoning that led to the chosen option. What made it preferable to the alternatives? What trade-offs were accepted?
Expected outcome: What should change as a result of this decision? What would "success" look like?
Review date (if applicable): Some decisions have a natural review point — "we'll try this for 3 months and then evaluate." Recording the intended review date ensures the review happens.
DECISION LOG ENTRY
ID: D-042
Title: Switch from synchronous to asynchronous email notifications
Date: 2026-10-18
Made by: @product-lead (with input from @eng-lead and @ops-lead)
DECISION:
Customer notifications will be sent asynchronously via a job queue
(Redis + Bull) rather than inline in the request/response cycle.
CONTEXT:
Synchronous email delivery was causing p99 API response times of 1.8
seconds (target: 500ms). The slowness was traced to our email provider's
API, which has 600-900ms latency under typical load.
ALTERNATIVES CONSIDERED:
1. Switch email provider: rejected — migration cost 4-6 weeks; other
providers had similar latency under high volume.
2. Cache email templates to reduce provider calls: rejected — doesn't
address the fundamental issue of blocking on external API.
3. Accept the latency: rejected — p99 1.8s is above our SLA and
measurably hurts conversion on checkout flows.
WHY THIS CHOICE:
Async delivery via job queue decouples API response time from email
delivery time. Adds minor complexity (job monitoring, retry logic)
but is a well-understood pattern with existing infrastructure support.
Trade-off accepted: customers don't receive email in real-time;
typical delay will be < 30 seconds under normal load.
EXPECTED OUTCOME:
API p99 response time drops to < 500ms on checkout endpoints;
email delivery delay < 30 seconds typical, < 5 minutes worst-case.
REVIEW DATE: 2027-01-18 (3 months post-implementation: validate
latency targets met and monitoring is sufficient)
A decision log is only useful if entries can be found. Basic structure:
By domain/area: A decision log organized by domain (Engineering, Product, Operations, HR, etc.) makes it easy to find all decisions in a specific area. This is the recommended primary organization for most organizations.
Chronologically within domain: Within each domain, entries ordered newest-first so recent decisions are immediately visible.
Cross-referenced by project or system: For decisions that relate to a specific project or system, a reference from the project/system documentation to the relevant decision log entries (and vice versa) improves discoverability.
Searchable: Whatever tool hosts the decision log should support full-text search. An engineer who remembers "we discussed Redis vs. Kafka" should be able to search for "Redis" and find the entry.
The ADR connection: In engineering contexts, Architectural Decision Records (ADRs) are a well-established format for documenting technical decisions, pioneered by Michael Nygard (2011). The ADR is domain-specific — it covers technical architectural decisions — and the general decision log covers the broader organizational scope. For engineering teams, the ADR collection IS the decision log for technical decisions; the general decision log covers product, process, and organizational decisions.
The decision log should live in the team or organization's knowledge base tool — wherever documentation is kept and searched.
Notion database: A Notion database with properties for each field (date, domain, status, maker) is searchable and filterable. The decision log as a Notion database lets teams filter by domain, date range, or status. This is a good choice for teams already in Notion.
Confluence page: A table of decisions with links to individual pages for each entry. Searchable via Confluence's search. Higher contribution friction than Notion but suitable for organizations already on Atlassian.
Markdown files in a repository (ADR-style): Each decision is a markdown file in a decisions/ or docs/adr/ folder, named by number and title. Version-controlled, reviewed via PR, searchable via code search. Best for engineering teams with a docs-as-code practice.
A dedicated Google Doc or spreadsheet: A simple spreadsheet with one row per decision works for small teams. Higher maintenance burden at scale; suitable for teams of up to ~15-20 people.
The tool is less important than the habit. A decision log in a spreadsheet that's updated consistently is more valuable than a well-designed Notion database that's updated sporadically.
A decision log that isn't updated is a decision log that doesn't exist. The mechanisms that make the habit stick:
The "does this go in the log?" trigger: At the end of every meeting that included significant discussion, the note-taker asks: "Did we make any decisions that belong in the decision log?" This takes 30 seconds. If the answer is yes, the entry is written within 24 hours while the context is fresh.
The agenda item: For scheduled decision meetings (strategy reviews, architecture reviews, planning sessions), add "Update decision log" as a standing agenda item. The person who owns the log or the note-taker handles this as part of the meeting follow-up.
The PR description for technical decisions: For engineering teams, when a significant technical decision is implemented, the PR description includes a link to the decision log entry (or the ADR). The link is forward (PR → decision) and backward (decision → implementation PRs). This connects the decision to its execution.
The onboarding reference: New team members are directed to the decision log as part of onboarding. "Read the last 6 months of decision log entries for the area you'll be working in" is a useful onboarding task that gives new employees context that would otherwise take months of osmosis. New employees who actually use the decision log are more likely to contribute to it.
A decision log entry is not permanent in the sense of unchangeable. Decisions can be revisited when:
The conditions that drove the decision have changed. "We chose this vendor because it was the most cost-effective at our scale — now we're 5x that scale and the economics have changed."
The expected outcome wasn't achieved. "We expected this architectural choice to solve the latency problem. It did, but it created a new one we didn't anticipate."
The review date arrives. "We said we'd evaluate this decision in 3 months. It's now 3 months. Here's what we found."
When a decision is revisited, the log entry should be updated to reflect the outcome: was the decision upheld, revised, or reversed? A decision log that includes retrospective outcomes is significantly more valuable than one that only records intentions.
Update the entry rather than creating a new one: "Updated October 2027: original decision held. Performance targets achieved. Memory management overhead was lower than expected."
A well-maintained decision log is one of the most effective onboarding tools an organization can offer. A new employee who reads the decision log for their domain over their first two weeks gains:
This context is usually acquired over months through conversation and osmosis. A decision log compresses this substantially — especially valuable for senior hires who are expected to make decisions in their domain quickly.
Setup: A 15-person operations team at a logistics company. They make 3-5 significant process decisions per week. No decision log. The team lead spends an estimated 2 hours per week in meetings where decisions already made are re-debated, because no one can remember what was decided or why.
What they build:
They create a Notion database with the fields above. They add "decision log update" to the standing agenda of their weekly team meeting.
Week 1: 3 entries. Small.
Month 1: 18 entries covering decisions from the month. Two entries explicitly prevent re-debates in team meetings — the person proposing an alternative is referred to the entry showing the prior discussion.
Month 3: A new operations manager joins. She reads the decision log as part of her onboarding. She asks intelligent questions about 3 decisions she wants to revisit, with specific reasoning about why the conditions have changed. Two are revisited and upheld; one is updated. She's productive significantly faster than her predecessor.
Month 6: The team lead's time in re-debate meetings drops from 2 hours per week to under 30 minutes. The decision log is searched 20-30 times per month.
A decision log is organizational memory made searchable. The practice of recording decisions at the time they're made — with the context, alternatives, and reasoning that make the record useful — takes 15-30 minutes per significant decision and pays dividends every time someone asks "why do we do it this way?" or "didn't we discuss this before?" The teams that maintain decision logs don't have better decision-making processes than teams that don't; they have the same quality of decisions, but those decisions accumulate into a reference that makes every subsequent decision more informed and every new team member's ramp-up faster. The decision log is the infrastructure that converts a team's decision-making effort into lasting organizational knowledge.
More WebSnips articles that pair well with this topic.
How to run a documentation audit — a practical guide for teams who want to systematically assess what documentation exists, what's accurate, what's missing, and what should be removed, producing a clear action plan for a knowledge base that's trustworthy and complete.
How to break down knowledge silos — a practical guide for teams and organizations where critical knowledge is trapped in specific people, teams, or systems, creating organizational brittleness, slowing decisions, and widening capability gaps between teams.
How to build a company handbook — a practical guide for founders, operations leaders, and HR teams who want a handbook that communicates what the company values, how it works, and what employees can expect, without producing a bureaucratic document no one reads.
How to build a company knowledge base — a practical guide for teams and organizations who want to capture institutional knowledge, reduce repeated answering, and make organizational context accessible to every employee regardless of when they joined.
How to capture knowledge from departing employees — a practical guide for managers and HR teams who want to systematically extract institutional knowledge before it leaves with an employee, rather than discovering the gaps after they're gone.
How to create a knowledge-sharing culture — a practical guide for teams and leaders who want knowledge sharing to be a natural part of how people work, not a program that requires constant top-down pressure to maintain.