§ 96
Narratives, Not Slides
An argument cut down to slides and bullets loses the links between its points, so the gaps and warnings that prose would have exposed pass through the review unnoticed.
Keep in mind
For decisions that matter, write prose, not bullets
What to do
For a decision that is expensive to reverse, or that people outside the team must approve, write the proposal as a few pages of prose: the problem, the options considered, the trade-offs and the recommendation. Open the review with everyone reading it in silence, then discuss. Do not write one for a reversible change or for a question a quick prototype will answer; build the prototype instead.
Why it happens
A bullet list records claims without the links between them: which point rests on which, and which one matters most. When an analysis is condensed to fit a slide, the reasoning that would expose a gap or a warning is what gets cut, and each step up a hierarchy condenses it again; the board that investigated the loss of Space Shuttle Columbia found that information is "inevitably lost" this way. Prose forces the author to state the links, and a group that reads the document in silence at the start of the meeting argues about the same text rather than about the presenter's delivery. The price is time: Bezos says a good memo can take a week or more, so the practice pays only for decisions worth that week.
When it stops applying
Working Software over Comprehensive Documentation: when running code would settle a design question faster than prose, a document written first spends a week recording guesses, and a design doc that is really an implementation manual should not be written at all.
Source
Jeff Bezos, 2017 Letter to Shareholders (Amazon.com, Inc., 2018) — "We don't do PowerPoint (or any other slide-oriented) presentations at Amazon. Instead, we write narratively structured six-page memos.", read silently at the start of each meeting, and a memo that "might take a week or more"; Columbia Accident Investigation Board, Report, vol. I (2003), ch. 7, "Engineering by Viewgraphs" — "When engineering analyses and risk assessments are condensed to fit on a standard form or overhead slide, information is inevitably lost."; Malte Ubl, Design Docs at Google (industrialempathy.com, 2020) — the engineering form, and design docs that are "really implementation manuals" as a sign that none was needed. The counter-force is from the Manifesto for Agile Software Development (2001).
Read the sourceCite this
Hammurabi, § 96, “Narratives, Not Slides.” https://kanywst.github.io/hammurabi/laws/narratives-not-slides/
BibTeX
@misc{hammurabi-narratives-not-slides,
title = {Narratives, Not Slides},
author = {{Hammurabi contributors}},
note = {Hammurabi, § 96},
url = {https://kanywst.github.io/hammurabi/laws/narratives-not-slides/}
}Read in a column
- Working as a team Next in the column: Disagree and Commit
Related laws
- 75Working BackwardsTeams that start from a solution often build things no customer needed; starting from the announcement exposes that early.
- 32Curse of KnowledgeOnce you know something, you can't easily imagine what it's like not to know it.
- 01Type 1 vs Type 2 DecisionsTeams spend the caution meant for irreversible decisions on ones they could easily undo.
- 104Programming as Theory BuildingA program's design lives in the heads of the people who built it, and the code and documents carry only part of it, so once those people are gone, changes tend to erode the design even with full documentation in hand.