Persuasive Writing — The Structure That Gets Design Docs and RFCs Approved

Introduction — When a Three-Week Document Gets Two Comments

You spend three weeks researching, running benchmarks, and writing a twelve-page design document. You share it, and two comments come in. One flags a typo, the other says "thanks, good read." Two months later, no decision has been made, and the document has become something people only find through search.

Go through this once and you usually land on the conclusion "our organization doesn't read documents." That's partly true. People really don't read documents. But that isn't a problem specific to your organization — it's the baseline condition for every organization, and a document written on the premise that it won't be read gets a different approval rate than one that isn't.

This post is for people writing something that needs approval — a design doc, an RFC, a proposal, an incident follow-up recommendation. The previous two posts on the structure of persuasion and handling objections covered conversations. This one covers the situation where the writer isn't in the room.

Decision First — Put the Decision, Not the Journey, Up Front

The overwhelming majority of documents engineers write are organized in the order the writer solved the problem: background, current-state research, comparison experiments, and finally, at the end, the conclusion. That's the path the writer took to understanding, not the path the reader needs.

The curse of knowledge explains well why this keeps happening. It's a concept named by Colin Camerer, George Loewenstein, and Martin Weber in a 1989 paper: once you know something, you can't imagine not knowing it, and you can't strip that knowledge away even when pretending not to know would be in your own interest.

The popular illustration always cited for this concept is Elizabeth Newton's 1990 tapping experiment. One person taps out the rhythm of a familiar song with their fingers while another tries to guess the song; the tapper predicted the listener would get it right about half the time, but the actual success rate was around 2.5 percent. That said, it's worth being honest here: this study is a doctoral dissertation that spread through popular books, and it's hard to call it a well-replicated result. It's safer to use it as an illustration than to cite the number itself. The concept itself — that people who know something systematically overestimate what people who don't know can grasp — has been observed across a fair number of domains.

The practical prescription is simple. Put three things in the first paragraph: what decision you're asking for, when it's needed by, and what changes as a result of that decision. Write the title as a decision too, not a topic. Not "Reviewing Our Caching Strategy" but "Proposal to Add a Cache Layer to the Read Path — Approval Requested by August 15." The reason to open it from a notification list needs to live inside the title itself.

Amazon is a well-known example of enforcing this structure at the organizational level. In 2004 it banned slide decks from executive meetings and required six-page narrative memos instead, and the meeting opens with everyone silently reading for 20 to 30 minutes. The stated reasoning at the time was that narrative sentences expose the logical gaps that slides tend to hide. Write in bullets and the relationships and relative importance between items disappear. Write in sentences and you're forced to use words like "therefore" and "however," and the moment you do, a hole in your own argument becomes visible to you first.

Showing the Alternatives You Rejected Is What Separates a Proposal from an Advertisement

A document that contains only one option isn't a proposal — it's an advertisement. From the reader's side, that kind of document isn't a request for approval; it's homework, because now they have to go figure out what the other options were themselves.

The architecture decision record is the format that enforces this. It has four fields — context, decision, status, consequences — and the consequences field is meant to record not just the good outcomes but also what you're accepting you'll have to live with as a result of this decision. The alternatives section in an RFC template serves the same purpose.

O'Keefe's 1999 meta-analysis, cited in the previous post, applies here too. Messages that raised the counterargument and answered it beat one-sided messages on both credibility and persuasiveness (42 studies, d = 0.16), and messages that raised the counterargument but never answered it did worse than one-sided messages (65 studies, d = -0.10). Filling out the alternatives section as a formality costs you.

Writing up a single alternative properly takes three lines. One line for what it is. One line for the conditions under which it would actually be the right answer. One line for why it isn't, given our conditions. The second line is the crux. Skip it and write only the third line, and you're just setting up a strawman to knock down — and readers can usually tell.

For example:

Adopt a third-party auth service. If the team is small and the audit requirements are standard, this is almost always the better choice. In our case, our internal audit logs require session-level raw retention rather than user-level, and none of the three vendors we evaluated support that shape.

One more section is worth adding: "if this proposal is wrong, here's why." This is where you write the objection you couldn't answer yourself. It looks like it costs you trust; it actually does the opposite, and more than anything, it keeps that objection from coming back as an incident after approval.

Turn the Cost of Doing Nothing into a Number

Most proposals argue "this will make things better." But what the decision-maker is actually comparing this against isn't another proposal — it's the status quo. And nobody writes up the cost of the status quo. So the default wins.

Status quo bias itself has been observed repeatedly across many domains since Samuelson and Zeckhauser's 1988 study. But the common move of automatically connecting it to loss aversion has drawn considerable pushback recently. David Gal and Derek Rucker argued in a 2018 paper that the evidence that losses generally loom larger than equivalent gains is, at present, insufficient, and that it depends heavily on context — and that argument has drawn counter-rebuttals of its own. So advice along the lines of "people feel losses twice as strongly, so frame it as a loss" is risky to cite right now. Instead, stick to a much simpler fact: if the comparison isn't in the document, the comparison doesn't happen.

Write the cost of inaction as three numbers.

First, what's leaking out right now, every week. Wait times, on-call page counts, hours of manual work, rollback counts — anything already being measured, or pullable from a log, is enough. Second, the trend in that number. Put the value from six months ago next to today's value, and the pairing becomes an argument on its own. Third, how much more expensive this gets the longer you wait. If the number of things needing migration is growing by some percent every month, that number is directly the interest rate on delay.

One common failure mode is worth flagging here: manufacturing a number when you can't actually produce one. One unsupported ROI estimate drags the credibility of the entire document down with it. In that situation, it's much better to write something like this:

This cost isn't currently being measured. Instrumentation can be added within two weeks, and that's the first step of this proposal. If the measured result comes back under five hours a week, I won't pursue the remaining steps.

Write for the Person Skimming

A large share of why documents don't get approved comes down to the fact that they don't get read. The Nielsen Norman Group's eye-tracking research reports that users read only 20 to 28 percent of the words on a page on average, and the F-shaped scan pattern first described in 2006 has now been observed repeatedly for close to twenty years. This is web-content research, but there's no reason a decision-maker opening a document five minutes before a meeting reads more diligently than that.

So a document that needs approval effectively has to be two documents at once: a thirty-second one and a thirty-minute one. And the thirty-second version can't live in a single summary section — it has to be distributed across the entire document.

Concretely, there are four moves.

Write subheadings as sentences, not nouns. Not "Performance Analysis" but "78 Percent of Read Latency Comes from a Single Query." If the argument comes through from the table of contents alone, the document also works for someone skimming.

Put the conclusion in the first sentence of each paragraph. The reason the F-shaped pattern shows up is that people read the front of each paragraph and move on. Start a paragraph with the evidence and end with the conclusion, and the conclusion never gets read.

Use tables only for comparison. A table is a strong element that grabs the eye, so turning non-comparative content into a table burns the reader's attention on something that doesn't matter.

Limit bold to one instance per section. Bold three things and it's the same as bolding nothing. And don't write your argument in bullets. Bullets are only honest when items are genuinely parallel; when there's a causal or conditional relationship between pieces of evidence, bullets erase that relationship. This is exactly the same reasoning behind Amazon banning slides.

The Paragraph That Survives a Meeting You Aren't In

Here's the thing that matters most in practice and that almost nobody trains for: your document gets quoted in meetings you're not in. Your manager carries it into the meeting above them, someone on another team pastes it into their own channel, or six months from now someone finds it through search. What survives at that point isn't the whole document — it's one paragraph.

That paragraph needs to meet four conditions.

It has to stand on its own without the preceding context. Phrases like "the approach mentioned above," "this issue," or "that component" lose their meaning the instant they're cut out. Use proper nouns and name specific things concretely.

The numbers and dates have to live inside the paragraph itself. Whoever is quoting it shouldn't have to go dig it back up.

The ask has to be inside it. Leave only situational description, and nothing happens wherever it gets quoted.

It has to be two or three sentences long. Go past a size someone can copy and paste, and it doesn't get quoted — it gets summarized instead. The moment it gets summarized, you lose control over it.

One more thing worth adding here: repeat the same sentence in the same form. The phenomenon where a statement gets rated as more true the more it's repeated is one of the findings in the persuasion literature that has held up reasonably well under replication. Dechêne and colleagues' 2010 meta-analysis, synthesizing 51 studies, reported an effect in the range of d = 0.39 to 0.50, and a more recent large-scale re-synthesis found g = 0.37 remaining even after correcting for small-study bias. The practical implication is: don't rephrase your wording fresh every time you write. Vary it every time and you lose the benefit of repetition, and multiple slightly different versions end up floating around the organization.

The boundary here is worth writing down too. This effect doesn't discriminate between true and false statements. So repetition isn't a technique — it's a responsibility. Only repeat sentences you've actually verified, and if one later turns out to be wrong, correct it with the same intensity you repeated it with.

Rewriting a Weak Proposal Paragraph

Here's an opening paragraph in a form you see constantly.

Our current auth module has a number of problems. There's a lot of legacy code, test coverage is low, and it's been getting harder to maintain lately. There's some consensus within the team that this needs improvement. Given that, we're proposing a refactor of the auth module overall. Details below.

Grammatically fine, sounds diligent, and does nothing. Count what's missing: there's no decision being requested — "we're proposing" isn't a request for a decision. There isn't a single number. "Lots of problems" is unfalsifiable but also carries zero information. There's no cost of doing nothing. There are no alternatives considered. There's no deadline. And cut out of context, there's nothing that tells you which company's, which document's paragraph this even is.

Here's the same content, rewritten.

I'm requesting approval to replace the token-validation path in the auth module over three weeks, starting the third week of August. Five of our twelve incidents over the last six months came from this path, and those five had an average recovery time of 47 minutes — twice the average for other domains. If we don't touch this now, the September social-login work will hit the same code again, and by then there will be twice as much to unwind. We also considered a full rewrite and adopting a third-party auth service; the former needs more than four months, and the latter doesn't meet our internal audit logs' requirement for session-level raw retention. The failure criteria are explicit: if the existing integration test suite doesn't pass in full within three weeks, we roll back and run the September work on top of the current code.

One paragraph, six things packed in: the decision and deadline being requested, the strongest evidence — actual measurements — the cost of doing nothing, two rejected alternatives with reasons, and failure criteria. You could paste this into any meeting and it would be judgeable entirely on its own.

It got longer. In this trade, that's generally a good deal. A short document gets read; a complete paragraph gets decided. If you're in a situation where you need to persuade someone the same way verbally in a meeting, the structure for spoken explanation covered in system design interview prep is a useful reference.

The Moves That Actually Work in Documents

None of these eight require writing talent. All of them are questions of placement and inclusion. Most of what it takes to persuade through writing isn't prose style — it's judgment about what goes where.

Closing — Making Approval Cheaper Than Cancellation

Persuading through a document isn't about changing the reader's mind. It's about designing the proposal itself so that the risk of approving looks smaller than the risk of not approving. Writing the failure criteria yourself first, spelling out how to roll back, and surfacing the objection you couldn't answer — all of it works in that direction.

I'd suggest changing exactly two things in the next document you write: open the first paragraph with the decision you're requesting, and build one paragraph that stands on its own without context. Everything else can be added once those two are in place.