Writing the Decision

Every written argument has a shape, whether or not the writer chose one. The reader imposes a hierarchy as they go, deciding which claims are the main ones and which serve others, because that is the only way a person can hold a long argument in mind.

If you do not supply the hierarchy, the reader builds one, and the one they build will not be yours. Most bad technical documents are not wrong. They are documents in which every sentence appears to be at the same level of importance, so the reader gives up and grades the effort instead of the argument.

The shape that works

One governing thought at the top. Beneath it, a small number of ideas that support it. Beneath each of those, the ideas that support them, down to the raw material of queries and code.

Three rules hold it up. An idea at any level must be a genuine summary of the ideas grouped beneath it, not a label for the pile. Ideas in a group must be the same kind of idea, so that summarizing them is possible at all. Ideas in a group must be in a deliberate order rather than the order they occurred to you.

Read downward, the pyramid is a conversation. “Adopt a three-class stocking rule at the April freeze” provokes an immediate and predictable why, and the reasons beneath it are the answer. Each reason provokes its own how do you know, and the evidence beneath answers that.

When a document feels tedious, it is usually because it is answering questions the reader has not yet been made to ask.

The opening and the pyramid are one structure

The opening exists to make the reader want the question that your governing thought answers. Establish the situation they already accept, introduce what has changed and what it has cost, and let the recommendation land as the answer to the question that creates.

This is not a separate technique bolted onto the front. It is the top of the pyramid, written out.

Headings have to carry the argument

Write the headings before the prose. Full sentences, each an assertion.

“Benchmark results” is a filing label. “The misses are concentrated in 8 percent of items, and those items strand repair jobs” is a claim. The first transfers analytical work to the reader. The second does the work for them, which is what they are paying for.

Then read the headings in sequence, ignoring the body entirely. If they make the case alone, the structure holds. If they read as a table of contents, the structure is decorative. Rearrange until they make the case, and only then write underneath them.

Senior readers do the heading-only read whether or not you designed for it. Designing for it means they get your argument rather than a guess at it.

Two shapes of support, and the test that tells them apart

Reasons hold up a recommendation in one of two arrangements, and confusing them is a common source of arguments that go nowhere.

Parallel reasons each support the recommendation on their own and together add up to a case. The cash and the misses sit in different items; the current rule cannot tell them apart; the exception path can be closed. Any one being true is a point in favor, and the case survives the loss of one of them in weakened form. This is what most decision write-ups should use, because it is robust to the ordinary fate of evidence, which is that one of your three reasons turns out to be shakier than you thought.

A chain runs step to step, with the recommendation as the last link. Expedite cost is unpriced where expedites are requested, therefore requesters cannot learn what they cost, therefore volume will not fall through effort, therefore the cost must be routed back to the requester. A chain is more persuasive than a parallel group when it holds, because it reads as a proof rather than a pile. It is also brittle in a way people underestimate: an objection to any single link takes down everything after it, and a reader who rejects step two has no reason to read steps three and four.

The test takes ten seconds. Read your reasons and remove the second one. If the argument still stands, you have a parallel group. If it collapses, you have a chain, and you should either say so plainly, that the case rests on this, or go find independent support so that it does not.

The failure worth guarding against is writing a chain while believing you have written a group, and then being surprised when one challenged premise takes the whole recommendation down.

Order is a choice, not an accident

Parallel reasons can be arranged by time, by structure, or by importance, and the right arrangement depends on what the reader is checking. Time order suits a sequence of events. Structural order, by region or item class or team, suits a reader auditing coverage. Importance order suits a reader deciding whether to keep reading, which is most of them.

What is not acceptable is the order the reasons occurred to you. That is the one arrangement guaranteed to carry no information for the reader.

Layers, not dumbed-down copies

A one-page version and a full note are not two audiences receiving different amounts of truth. They are the same argument at two depths.

The one-page version contains the choice, the alternatives, the recommendation, the reasons, the flip conditions, and the rule. The full note adds the economics and the evidence trail. Methods, code, and formulations sit behind both.

The constraint that matters: if the ranking in the appendix disagrees with the recommendation on page one, the write-up is wrong. Layers must be consistent, not merely shorter.

What to cut

Everything that was scaffolding for you rather than support for the reader.

The exploratory cuts that went nowhere. The method you tried first. The chronology of the project. The chart that is in the deck because it was made rather than because it argues for something. Sunk production cost is not an argument for inclusion, and it is the most common one actually operating.