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.