trees-maps-theorems

# Trees, Maps, and Theorems This skill distills Jean-luc Doumont's *Trees, Maps, and Theorems: Effective Communication for Rational Minds* (Principiae, 2009) into a procedure for producing communication that busy, selective readers can act on. The title is the method: organize content as a **tree**, give the audience a **map** of that tree, and state each point as a **theorem** — the assertion first, the proof after. Communication is not about what you want to say; it is about what you want the audience to *do* as a result. Optimize for their reading, not your writing. ## The three laws Apply these to every artifact, at every level, before any other rule. When two rules conflict, the laws win; when the laws conflict, audience wins. 1. **Adapt to your audience.** Decide who will consume this and what they need in order to decide or act. Write for their questions, vocabulary, and available time — not for your process. "What I did, in the order I did it" is almost never the right structure. 2. **Maximize the signal-to-noise ratio.** Noise is anything that does not carry your message: hedging, boilerplate, decoration, repeated context the reader already has, chartjunk, screenshots of things nobody must inspect. Removing noise beats amplifying signal. 3. **Use effective redundancy.** Important messages should survive skimming: state them in the title AND the summary AND the relevant section; in a talk, say it and show it. Redundancy is for the essentials only — redundant noise is the worst of both worlds. ## Messages, not information Information is fact; a message is what the audience should conclude or do. - Information: "The test suite takes 14 minutes." - Message: "The test suite is too slow to gate every commit — run it nightly instead." Apply the **"so what?" test** to every title, heading, paragraph, slide, and figure caption. If a reader can answer "so what?" faster than you stated it, you wrote information, not a message. State conclusions as complete sentences; "Results" is a label, "Latency doubles above 100 concurrent users" is a message. ## Trees: structure the content hierarchically - Break content into **3–5 branches per level**. More than ~5 items at one level means a grouping is missing; one item means the level is fake. - Make each branch meaningful on its own: a reader who opens only one section should get a complete, coherent unit. - Order branches by what the audience needs first (usually: conclusion → support → detail), not by chronology of your work. - Depth is fine; unmapped depth is not. Every level you add needs a map (below). ## Maps: reveal the structure before the detail Readers navigate; they do not read linearly. At every branching point, tell them where they are and what is coming. **Open every substantial artifact with a foreword that answers four questions, in order:** | Element | Question it answers | |---|---| | **Context** | What situation is this about? What does the reader already know? | | **Need** | Why must something be done — and why now? | | **Task** | What was done (or will be done) about the need? | | **Object** | What does *this document* cover, and how is it organized? | Then preview the branches ("Section 2 shows X; Section 3 proposes Y"). Inside the body, open each section with a one-line map of its subsections. A reader who reads only your forewords should still leave with every main message. ## Theorems: state the message, then prove it Lead every unit with its message as a full assertion; everything after is proof. - **Documents**: the summary states the main messages and conclusions — self-contained, because most readers read nothing else. - **Sections**: the first paragraph states the section's message. - **Paragraphs**: the first sentence is the point; the rest supports it. If you must skim a colleague's paragraph, you read its first sentence — write so that this works on yours. - **Headings and slide titles**: prefer sentences ("Caching removes the p99 spike") over labels ("Performance"). - Never bury the conclusion at the end "to build up to it." Rational minds accept a stated theorem and then check the proof; they resent a mystery. ## Written documents Structure any report, plan, RFC, or doc as four components: 1. **Header** — informative title + abstract. The abstract compresses the whole document: need, task, findings, conclusion. No suspense. 2. **Foreword** — context, need, task, object (see Maps). 3. **Summary** — the main messages and recommendations, self-supporting. 4. **Body** — the tree of sections, each theorem-first, ending with a conclusion that restates the messages (effective redundancy) and names the next action and its owner. For short artifacts (comments, emails), collapse this: one status line that IS the message, bullets as proof, explicit next action. The structure scales down; it never disappears. ### Applied to everyday engineering artifacts - **Issue comment / status update**: first line = the message ("Fix shipped and verified; nothing remains on this issue" / "Blocked: X must do Y"). Bullets = evidence with links. Last line = who does what next. - **PR description**: title is a message, not a location ("Stop retrying 409s" not "Update checkout logic"). Body: why (need), what changed (task), how it is verified (proof), what reviewers should look at (map). - **Plan**: recommendation first, then the map of phases, then per-phase messages with their proof. A plan whose summary cannot be approved without reading the body has failed the summary. - **Incident report / RCA**: impact and root cause in the first two sentences; timeline is an appendix, not an opening. ## Oral presentations and slides - **Plan the talk around one main message** the audience must retain, and at most 3–5 supporting messages. Time is the audience's, not yours. - **Open** with: attention getter → need → task → preview (the map). Do not open with an outline slide of labels; open with why they should listen. - **One message per slide**, stated as a full sentence, ideally as the slide title. Everything else on the slide is proof of that sentence. - Slides support the speaker; they do not duplicate the script. If the slide can be read instead of listening to you, cut the slide or cut you. - Maximize signal-to-noise ruthlessly on slides: no decorative images, logos on every page, or bullet pyramids. White space is not wasted space. - **Close** by restating the main messages and the call to action (effective redundancy) — never end on "Questions?" as the final content. ## Graphical displays - A graph answers a question; pick the graph type from the question, not from the tool's default. Trends → lines; comparison → bars; exact values → a table, not a graph. - **The caption states the message**: "Throughput degrades sharply beyond 8 workers," not "Throughput vs. worker count." A figure whose caption is a label forces every reader to re-derive your conclusion. - Maximize data-ink: remove gridlines, frames, 3D effects, and colors that encode nothing. Label curves directly instead of using a legend when practical. - Design each figure to be understood standalone — figures are harvested out of documents and pasted into other ones. ## Pre-publish checklist Run this before posting/sending any nontrivial artifact: - [ ] Named the audience and the action you want from them? - [ ] First line/title/abstract states the main message (passes "so what?")? - [ ] Foreword answers context, need, task, object? - [ ] Structure is a mapped tree — 3–5 branches, previewed before detail? - [ ] Every paragraph/slide/figure leads with its message? - [ ] Noise removed — hedges, boilerplate, decoration, known context? - [ ] Essentials redundantly encoded (title + summary + body)? - [ ] Next action and its owner explicit at the end? ## Attribution Method from Jean-luc Doumont, *Trees, Maps, and Theorems: Effective Communication for Rational Minds*, Principiae, 2009 (https://www.principiae.be/). This skill is a distillation for agent use, not a reproduction of the book.