Written-first culture, ADRs, and managing up
What it is
A written-first culture is one where decisions, designs and status exist as durable documents by default, and meetings are for the things a document cannot do. Three instruments and one habit:
DESIGN DOCS / RFCs the proposal, circulated for comment before
the work starts
ADRs architecture decision records: short,
immutable, one per decision, capturing
context, the decision, and the consequences
MEETING AUDIT no agenda, no meeting. No decision, shorter
meeting. Status meetings become async
updates.
MANAGING UP a monthly one-pager to your director:
progress, risks named early, and asks.
The unifying claim: decisions that are not written down get relitigated, and every relitigation costs the same argument again with worse memory and different people.
What this is confused with: documentation. Documentation describes how a system works now. A written-first culture is about capturing why a decision was made, at the moment it was made, which is the information that decays fastest and is impossible to reconstruct later.
Also confused: written-first and asynchronous-only. The point is not to eliminate conversation, it is that the conversation should start from a document and end in one. A design review with no pre-read is a meeting where six people hear an idea for the first time and are asked to evaluate it.
The problem it solves
Undocumented decisions are re-made, and each re-making is more expensive than the first.
March the team decides to use Postgres rather than DynamoDB
for the ledger, because of the multi-row transaction
requirement. Discussed in a meeting. Nothing written.
August a new senior engineer proposes DynamoDB. Nobody can
remember the full reasoning, only the conclusion.
Two days of debate, the same conclusion, plus
unnecessary friction.
November an architecture review asks why the ledger is not on
DynamoDB like everything else. The two people who
were in the March meeting have left.
Three days of investigation to reconstruct an
argument that took forty minutes originally.
A ten-line ADR written in March would have cost fifteen minutes.
And the meeting failure, which is the same problem in the time domain:
A weekly one-hour status meeting, 9 people:
9 person-hours per week = ~1.1 person-days
x 46 weeks = ~52 person-days a year
For information that is (a) already in the tracker, (b) relevant
to at most two people at a time, and (c) delivered in a format
nobody can search.
The same content as a written async update takes about 5 minutes
each to write and 3 minutes to read: ~1.2 person-hours a week,
and it is searchable.
And the managing-up failure, which is the most consequential for the lead personally:
A director with eight teams reporting through them hears from
your team when:
- something goes wrong
- a deadline is missed
- someone escalates about you
They have no independent view of your team's progress, risks, or
judgment, so their model of you is built entirely from
exceptions, and every exception is negative by construction.
The lead who sends a monthly one-pager has a director whose model
is built from the lead's own framing, updated before the news.
Mechanics
Design docs and RFCs
WHEN: before non-trivial work starts. The test is whether
someone could reasonably have done it a different way. If yes,
write the doc.
STRUCTURE that survives:
1. The problem, in user or business terms, with a number if
one exists
2. Constraints, including the non-obvious ones (compliance,
an existing contract, a team's capacity)
3. Options considered, at least two, with the cost of each
4. The recommendation, and the condition that decides it
5. What we are NOT doing, and why
6. Risks and how we would know if we were wrong
7. A rollout and rollback plan
REVIEW: circulated with a deadline for comments, then a meeting
ONLY if there is unresolved disagreement. Most docs do not need
a meeting, and the ones that do have a much better meeting
because everyone has read it.
Section 5, what we are not doing, is the one that prevents the most future argument, because the question that comes back in six months is almost always "why didn't you just...".
Architecture Decision Records
ADRs are deliberately smaller than design docs, and the constraints are what make them survive.
ONE DECISION PER RECORD.
NUMBERED AND IMMUTABLE. You do not edit an ADR to change the
decision; you write a new one that supersedes it, and mark the
old one superseded. The history is the value.
SHORT. Half a page to two pages. An ADR that takes an hour to
write does not get written.
IN THE REPO, next to the code, so it is found by the person
reading the code.
# ADR-014: Ledger stored in Postgres, not DynamoDB
Status: Accepted (2024-03-11). Supersedes none.
## Context
The ledger must record double-entry postings. A single business
event produces 2 to 8 rows that must all commit or none. Our
default datastore for new services is DynamoDB.
DynamoDB transactions are limited to 100 items and cannot span
tables, and our reconciliation query pattern is a range scan by
(account, time) with aggregate sums, which requires either a
secondary index per query shape or a separate analytics path.
Expected volume: ~40M postings/year, ~14 GB/year including
indexes. This is small.
## Decision
Store the ledger in Postgres, with postings in a single table
partitioned by month.
## Consequences
+ multi-row atomicity is a native transaction
+ reconciliation is SQL, so finance can be given read access
+ the volume is comfortably within a single instance for years
- diverges from the org default, so the on-call rotation needs
Postgres competence (see ADR-016)
- we own vacuum and partition maintenance
- if volume grows 100x this decision should be revisited; the
trigger is >500M postings/year
## Alternatives considered
DynamoDB with a transactional write of up to 8 items and a
separate analytics export: rejected because reconciliation
becomes a second system and finance cannot self-serve.
The "consequences" section including the negatives is what makes an ADR trustworthy, and the revisit trigger with a number is what makes it useful later: the November architecture review reads "revisit above 500M postings a year" and checks the current number instead of reopening the argument.
What deserves an ADR:
YES: choice of datastore, a language or framework introduction,
an API style, an auth model, a consistency model, a
significant deviation from an org standard, a decision to
accept known debt
NO: which library for date formatting, naming conventions,
anything a linter can enforce, anything reversible in an
afternoon
The meeting audit
NO AGENDA, NO MEETING. Circulated in advance, with the DECISION
the meeting exists to make. "Discuss X" is not a decision.
NO DECISION, SHORTER MEETING. If a meeting has no decision to
make, it is an update, and updates are written.
STATUS MEETINGS BECOME ASYNC UPDATES. Written by each person,
read by whoever needs it, searchable afterwards.
A PRE-READ, AND SILENT READING TIME. The Amazon-style practice
of opening a meeting with 10 to 20 minutes of silent reading
works because it removes the "did everyone read it" problem
entirely rather than hoping.
EVERY RECURRING MEETING GETS AN EXPIRY DATE. Meetings are
created for a reason and outlive it. A quarterly review where
each recurring meeting must be re-justified removes several
every time.
DECISIONS AND ACTIONS WRITTEN DOWN, IN THE MEETING, WITH OWNERS.
A decision that exists only in six people's memory will be
remembered six different ways.
The single highest-return audit action is deleting or async-ing one recurring status meeting, and the arithmetic (9 people, one hour, 46 weeks, 52 person-days a year) is usually enough to carry it.
Managing up: the monthly one-pager
One page, monthly, to your director. Same structure every time
so it can be skimmed.
WHAT SHIPPED 3 to 5 bullets, with the outcome, not
the activity. "Refunds latency p99 from
2.1s to 340ms" not "worked on refunds".
WHAT'S NEXT the next month, briefly.
RISKS named early, with your assessment and
what you are doing. THIS IS THE MOST
VALUABLE SECTION and the one people
omit.
"The identity dependency is unscheduled.
If it is not scheduled by the 7th we
build a two-day workaround. I do not
need help yet; I will tell you if that
changes."
ASKS specific, with what happens if the
answer is no. "I need a decision on the
Q3 headcount split by the 20th; without
it I will plan for the lower number."
PEOPLE one or two lines: someone doing
well and worth remembering at
calibration, or a risk.
Three properties make it work:
1. RISKS BEFORE THEY ARE NEWS. A director's worst experience is
learning about a problem from someone else's escalation. A
lead who names risks a month early is the lead they trust,
and this is almost entirely a function of habit rather than
judgment.
2. ASKS WITH A DEFAULT. "I need X by the 20th; absent an answer
I will do Y" is answerable. An open question is deferrable.
Same mechanism as unsticking a decision.
3. OUTCOMES, NOT ACTIVITY. A director cannot evaluate "worked on
refunds". They can repeat "refunds p99 went from 2.1s to
340ms" upward, and being repeatable upward is what makes a
one-pager travel.
The people section is the under-used one, because calibration rooms are months away and a director who has seen a name in three consecutive one-pagers alongside a specific artifact arrives with a prior.
Incident communications
FIXED CADENCE. Every 30 minutes during a Sev1, even if the
update is "no change, still investigating, next update at
14:30". A predictable cadence stops people asking, which is
itself a load on the responders.
AUDIENCE-APPROPRIATE DETAIL.
status page / customers: impact, scope, what to do, next
update time. No internals.
internal broad: impact, what is known, what is being tried,
who is commanding, next update.
responders: everything.
NO SPECULATION. "We believe it may be the database" becomes
"the database is down" in the third retelling, and it will
reach a customer.
BLAMELESS POSTMORTEM with action items that have OWNERS AND
DATES. An action item without both is a wish, and the
measurable form of postmortem quality is the completion rate
of its actions.
A worked example: a lead who was invisible until something broke
A lead of nine, eighteen months in post, strong delivery, and a performance conversation in which their director described them as "hard to read" and said they had "limited visibility into what the team is doing." The lead's own view was that they were shipping and not complaining, which they had assumed was the ideal.
The audit:
DECISIONS
Design docs written in 18 months: 2
ADRs: 0
Decisions re-litigated in the previous quarter, counted from
meeting notes and threads: 6, consuming an estimated 9
engineer-days
MEETINGS
Recurring team meetings: 5, totalling 4.5 hours per person
per week
Of those, meetings with a written agenda: 1
Meetings whose purpose was a decision: 1
Weekly status meeting: 9 people x 1 hour = 52 person-days a
year
UPWARD COMMUNICATION
Written updates to the director in 18 months: 0
Times the director learned of a team problem from someone
else first: 4
"Four times the director learned about my team's problem from someone else" is the finding, and it fully explains the "hard to read" feedback without needing any other explanation.
The changes:
1. ADRs, introduced with a template and a rule: any decision
someone could reasonably have made differently gets one, half
a page, in the repo.
First quarter: 11 ADRs written, median length 340 words,
median time to write 18 minutes.
The team back-filled 4 for decisions already made, which took
longer (the reasoning had to be reconstructed) and was worth
it: the ledger/Postgres decision was one of them, and it was
questioned two months later by an architecture review and
answered by linking the ADR.
Decisions re-litigated the following quarter: 1.
2. MEETING AUDIT.
- the weekly status meeting was replaced with a written
async update, 5 minutes to write, posted by Tuesday noon
-> recovered ~48 person-days a year
- two recurring meetings were found to have outlived their
reason and were deleted
- the remaining three got written agendas with a named
decision, and a rule that no agenda by the evening before
cancels the meeting
-> recurring meeting time per person: 4.5 h/week -> 1.5
The cancellation rule was invoked 3 times in the first
month and 0 times after that, which is how a forcing
function is supposed to work.
3. THE MONTHLY ONE-PAGER, started immediately.
Month 1 was awkward: the lead had to reconstruct what had
shipped, and found they could not express two months of work
as an outcome, which was itself a useful finding.
Month 3's risks section named an upcoming dependency
problem. The director, having been told a month early, moved
it in a planning conversation the lead was not in. The lead's
note: "the risk section did work I could not have done
myself."
Month 5: the director forwarded the one-pager to their own
VP, unedited. That is the outcome the format is designed for
and the lead had not anticipated it.
"The director forwarded it unedited" is the test of whether a one-pager is written in outcomes, and it is the mechanism by which a lead's work travels two levels up without them being in the room.
Twelve months later:
before after
design docs / ADRs 2 / 0 6 / 31
decisions re-litigated per
quarter 6 0-1
recurring meeting hours per
person per week 4.5 1.5
written updates to director 0 12
director learning of a problem
from someone else first 4 0
And the performance conversation the following year described the lead as "the person whose risks I hear about first," which is a sentence that came directly from the risks section of a monthly document, and cost roughly 30 minutes a month.
Two things that did not work, recorded honestly:
1. An attempt to require a design doc for everything produced
four documents in a month, three of which were for work
nobody would have done differently, and the practice was
quietly abandoned by the team within six weeks.
Replaced with the test: could someone reasonably have done
this a different way? That test produced 6 docs in a year,
all of which were read.
2. A shared "decision log" spreadsheet, separate from the repo,
which nobody updated after the second week. ADRs in the repo
next to the code worked because they were where the reader
already was.
The general lesson: a written artifact that lives away from
the work does not survive.
Production evidence
Architecture Decision Records were introduced by Michael Nygard in "Documenting Architecture Decisions" (2011), with the specific design constraints described here: one decision per record, numbered, immutable, superseded rather than edited, and stored with the code. The practice appears in the ThoughtWorks Technology Radar and is widely adopted, with tooling (adr-tools) and template collections maintained publicly.
Amazon's six-page narrative memo practice, replacing slide presentations, and its accompanying silent reading period at the start of the meeting, is the best-documented instance of written-first decision-making at scale, and the silent-reading detail exists precisely because relying on pre-reading does not work.
Google's design document culture and its published engineering practices treat a design doc with named reviewers as the durable artifact of a decision, and the same artifact is what promotion packets cite as evidence.
Blameless postmortems with owned, dated action items are specified in Google's SRE Book, which also identifies action-item completion rate as the measurable indicator of whether a postmortem process is real.
Incident communication at a fixed cadence is standard in PagerDuty's and Atlassian's published incident-response documentation, with the stated rationale that a predictable next-update time reduces inbound interruptions to responders, which is a load-shedding argument rather than a courtesy one.
Research on distributed and asynchronous work consistently finds that written, searchable decision records disproportionately benefit people who were not in the room, which includes future hires, other time zones, and anyone who joins the team after the decision.
The debate
Does written-first slow things down? It front-loads the cost and removes a larger recurring one. A ten-line ADR costs fifteen minutes and prevents a two-day re-litigation eight months later, and the observed rate in one team was six re-litigations a quarter costing about nine engineer-days. The legitimate objection is that a heavy documentation requirement produces documents nobody reads, which is why the test is whether someone could reasonably have decided differently.
Should ADRs be editable? No, and this is the constraint people most often relax. An edited ADR loses the history, which is the entire value: the useful artifact is "we decided X in March for these reasons, and superseded it in November for these other reasons", and an edited record shows only the current state, which the code already shows.
Are status meetings ever justified? For a team in crisis, in the first weeks of a reorganisation, or where the point is the social contact rather than the information, yes and say so. For steady-state information transfer, no, and the arithmetic, 52 person-days a year for nine people, usually settles it without further argument.
Is a monthly one-pager self-promotional? It is the mechanism by which a director's model of you is built from your framing rather than from exceptions, and every exception is negative by construction. The counter-argument, that the work should speak for itself, describes a world where your director has time to observe your team, and they have eight. The version that becomes self-promotional is one written in activity rather than outcomes.
Should risks always be surfaced upward? Named, yes; escalated, not necessarily, and the distinction is worth making explicit in the document. "Here is a risk, here is what I am doing, I do not need help yet, I will tell you if that changes" gives the director information without transferring the problem, which is what makes them trust the next one.
Does silent reading time in meetings work? Yes, and the discomfort is the point. Relying on people to pre-read fails often enough that the meeting degrades into a presentation, and ten to twenty minutes of reading is cheaper than an hour of a badly informed discussion.
Follow-up Q&A
"Why write down decisions rather than just the design?"
Because the reasoning decays fastest and is impossible to reconstruct. Documentation says how a system works now, which the code also says. A decision record says why this option was chosen over the alternatives, under what constraints, and what would make it worth revisiting, and none of that is recoverable from the code. In one team, six decisions were re-litigated in a single quarter at a cost of about nine engineer-days, and in each case the conclusion was the same as the original: they were paying for the same argument twice with worse information.
"What makes an ADR different from a design doc?"
Scope and lifecycle. One decision, half a page to two pages, numbered, immutable, and stored in the repo next to the code. You never edit an ADR to change a decision; you write a new one that supersedes it and mark the old one superseded, because the history is the value. A design doc is the proposal for a body of work with options and a rollout plan; an ADR is the durable record of one choice within it. The consequences section must include the negatives, and a revisit trigger with a number ("revisit above 500M postings a year") is what lets a future reviewer check a fact instead of reopening the argument.
"What is the meeting audit?"
No agenda, no meeting, with the agenda naming the decision the meeting exists to make, since "discuss X" is not a decision. No decision, shorter meeting, because an update is written rather than performed. Status meetings become async written updates. Recurring meetings get an expiry date and are re-justified quarterly, because meetings outlive their reason. And decisions and actions are written down in the meeting with owners, because a decision held in six memories is remembered six ways. The highest-return single action is usually converting one recurring status meeting: nine people for an hour over 46 weeks is 52 person-days a year.
"What goes in a monthly one-pager to your director?"
What shipped, in outcomes rather than activity; what is next; risks named early with your assessment and what you are doing; asks with a default; and a line or two on people. The risks section is the most valuable and the most commonly omitted, because a director's worst experience is learning about a problem from someone else's escalation. Phrase risks so they inform without transferring: "the identity dependency is unscheduled; if it is not scheduled by the 7th we build a two-day workaround; I do not need help yet and I will tell you if that changes."
"How do you know a one-pager is written well?"
If your director forwards it unedited. That only happens when it is written in outcomes rather than activity, because "refunds p99 went from 2.1 seconds to 340 milliseconds" is repeatable upward and "worked on refunds" is not. It is also the mechanism by which a lead's work reaches two levels up without them being in the room, which is worth more than most things a lead can do with thirty minutes a month.
"What are the rules for incident communication?"
A fixed cadence, typically every 30 minutes during a Sev1, including updates that say nothing has changed and when the next one is, because a predictable next-update time stops people interrupting the responders. Audience-appropriate detail: impact and next update time for customers, more for the internal audience, everything for responders. No speculation, because "we believe it may be the database" becomes "the database is down" by the third retelling and will reach a customer. And a blameless postmortem whose action items have owners and dates, with completion rate as the measurable indicator of whether the process is real.
Common misconceptions
"Documentation is the same as decision records." Documentation describes the current state, which the code also does. A decision record captures the reasoning, which nothing else preserves.
"Update the ADR when the decision changes." Editing destroys the history, which is the value. Write a superseding record.
"Written-first means fewer conversations." It means conversations start from a document and end in one. A design review with no pre-read is six people evaluating an idea they are hearing for the first time.
"Good work speaks for itself." Your director has eight teams and hears about yours through exceptions, which are negative by construction.
"Surfacing a risk means asking for help." Naming a risk with your plan and an explicit "I do not need help yet" gives information without transferring the problem, and that is what makes the next one credible.
"Everyone will read the pre-read." They will not often enough that the meeting degrades. Silent reading time at the start is cheaper than an hour of badly informed discussion.
Interview delivery note
Say this verbatim: "Decisions that are not written down get relitigated, and the second argument is more expensive than the first because the people who had the context have left. A ten-line ADR costs fifteen minutes; we were re-litigating six decisions a quarter at about nine engineer-days." The claim plus the arithmetic that makes it an argument rather than a preference.
The senior-versus-staff separator is the risks section of an upward update. A senior lead reports progress. A staff lead names a risk a month before it becomes news, with their own assessment, what they are doing about it, and an explicit statement of whether they need help. That gives the director information without transferring the problem, and it is why they trust the next one. The observable outcome, "the person whose risks I hear about first", is a reputation built from thirty minutes a month of a fixed-format document.
The second signal is knowing why a decision record must be immutable. Saying "you never edit an ADR; you supersede it, because the useful artifact is that we decided X in March for these reasons and changed to Y in November for these others, and an edited record shows only the current state, which the code already shows" demonstrates you understand what the artifact is for rather than that you have seen a template.
Further reading
- Michael Nygard, "Documenting Architecture Decisions" (2011), for the original ADR format and its constraints.
- Amazon's narrative-memo practice and its silent reading period, as documented in Jeff Bezos's shareholder letters and subsequent accounts.
- Google's SRE Book on blameless postmortems, including action-item completion rate as the measure of whether the process is real.
- PagerDuty's and Atlassian's incident-response documentation on communication cadence and audience-appropriate detail.
- The unblocking page, for the decision-latency measurement that a written decision record makes possible.