The PRD was seventeen pages long.
It covered the problem statement, the user research, the competitive analysis, the proposed solution, three alternative approaches considered and rejected, the edge cases, the dependencies, the rollout plan, and the success metrics.
It took three weeks to write. One engineer read it. Two others skimmed the summary section. The rest built what they understood from the kickoff meeting, which was three weeks before the PRD was finished.
The feature shipped. It wasn't quite what the PM meant. The rework cost six weeks.
This story is not unusual. It is, in some form, happening on your team right now.
The Problem Is Not the Writing
Here is the thing most writing advice gets wrong: engineers and PMs don't need to be taught grammar. They don't need more templates. They don't need shorter paragraphs or better bullet points.
The problem is upstream of all of that. It's a misunderstanding of what writing is for.
Most engineers and PMs write to document thinking they've already completed. The document is a record — of decisions made, analysis done, conclusions reached. It goes out into the world as a kind of transcript, evidence that the work happened.
This is not what the reader needs.
The reader — a staff engineer reviewing your design doc, a VP reading your strategy memo, a teammate parsing your Slack message at 9pm — needs something different. They need to know: what does this mean for what I do next?
They are not reading to understand your process. They're reading to make a decision, form an opinion, take an action, or understand a change that affects them. The best writing makes that thing effortless. Most professional writing makes it a scavenger hunt.
The shift from one to the other is not a grammar lesson. It is a change in orientation — from writing about your thinking to writing for your reader's thinking.
Why Engineers Write the Way They Do
Engineers are trained to show their work. In school, the grade goes to the derivation, not just the answer. In code review, the logic of the approach matters as much as whether it runs. This is correct. It is also the wrong instinct for most non-code writing.
The instinct translates into a specific pattern: chronological order. The engineer writes as they think — first this, then that, which led to this, which revealed that, therefore this conclusion.
This is a perfectly logical structure for someone reconstructing an analysis from scratch. It is a terrible structure for someone who just needs the conclusion.
The reader does not share your journey. They are not starting from where you started. They are starting from now, from their current context, from the decision in front of them. Beginning at the beginning costs them time they don't have and patience they can't spare.
Why PMs Write the Way They Do
The failure mode for PMs is different but related.
PMs often write to signal thoroughness. The long PRD, the comprehensive requirements doc, the status update with every detail — these are often not for the reader. They are for an internal audience that doesn't exist: the imaginary person who will evaluate whether enough work went into the thinking.
Length becomes a substitute for clarity. Covering edge cases becomes a substitute for making decisions. Describing every constraint becomes a substitute for saying which one matters most.
The PM who writes a twenty-page PRD has often done less intellectual work than the one who writes three pages — because the twenty-page version hasn't required them to choose. It includes everything, which means nothing is prioritized, which means the reader has to do the prioritization work themselves.
Thoroughness is a virtue. But thoroughness-as-signal is a tax on your reader's attention. And you only have so much of it.
The Core Principle: BLUF
The military has a writing convention called BLUF: Bottom Line Up Front.
The idea is simple and radical: your most important point — your conclusion, your recommendation, your ask — goes first. Everything after it is support.
This inverts the instinct of most professional writing. We are trained to build to a conclusion, to establish context before asserting, to earn the recommendation through the argument. BLUF says: skip that. Give me the conclusion. Then explain it.
This feels backwards until you think about it from the reader's perspective.
If you open with the context, I'm reading without knowing what I'm reading toward. I'm storing information without a frame for why it matters. When the conclusion finally arrives, I have to backtrack mentally and recalibrate everything I just read through that lens.
If you open with the conclusion, I know immediately whether this matters to me and why. Every piece of context that follows is already organized around something. I can skim the parts that don't change my view. I can drill into the parts that do.
BLUF in practice:
Instead of: "We've been seeing declining engagement in the notification flow over the last quarter. After reviewing the data and running several experiments, we've determined that the push notification timing is the primary driver. Based on this analysis, we recommend moving the notification window from 9am to 7pm..."
Write: "We recommend changing the notification window from 9am to 7pm. This single change is projected to recover 15% of the engagement decline. Here's why."
The information is the same. The reading experience is entirely different.
The One-Sentence Test
Before you write a document, you should be able to complete this sentence:
"After reading this, I need [specific reader] to [specific action or understanding]."
If you can't complete it, you're not ready to write. You haven't found the point yet.
This is not a formatting exercise. It is a diagnostic. The inability to state your point in one sentence usually means one of three things:
- You haven't finished your thinking and shouldn't be writing yet
- You're writing a document with multiple unrelated purposes, which means you should split it into multiple documents
- You know what you think but haven't committed to saying it clearly — usually because clarity invites challenge and ambiguity feels safer
The last one is the most common and the most costly. Engineers and PMs sometimes write vaguely on purpose — to hedge, to leave room for retreat, to avoid the discomfort of a definitive recommendation that might be wrong.
This is understandable. It is also a failure of the document's function. Your reader cannot act on ambiguity. They can only be confused by it, or build their own interpretation — which may not be yours.
The one-sentence test, applied:
Before you write a design doc, finish this: "After reading this, I need the team to understand that [X] is the right approach because [Y], and I need a decision by [date]."
Before you write a PRD, finish this: "After reading this, engineering needs to understand exactly what success looks like, what constraints they're working within, and what the one thing we cannot get wrong is."
Before you send a Slack message, finish this: "After reading this, [person] needs to know/do [specific thing]."
If the sentence is muddy, the document will be muddy. Clean the sentence first.
Write for the Reader's Job, Not Yours
Here is the question that will improve your writing more than any style advice:
What does this person need to do after they read this?
Not: what do I need them to know? Not: what do I need to explain? Not: what did I find out?
What do they need to do?
A VP reading your strategy memo needs to make a resource allocation decision. Write for that decision. What are the two or three things, clearly stated, that will determine whether they fund the approach? Put those at the center.
An engineer reading your PRD needs to understand scope and constraints well enough to estimate, plan, and build without asking you a hundred questions. Write for those questions. What will they ask? Answer those things explicitly. Leave out the competitive analysis they don't need.
A designer reading your brief needs to understand the problem to be solved and the constraints that bound the solution. They do not need the technical implementation details. They need the user's pain point described with enough specificity that they can design against it.
Most professional writing fails because it's written for the writer's perspective, not the reader's job. The writer knows what they've learned, so they write about learning. The reader needs to act, so they need to know what to do.
This reorientation — from your perspective to their job — is the single most powerful edit you can make to any document.
The Five Documents That Matter
The PRD
The PRD exists to answer one question: what does done look like, and why does it look like that?
Most PRDs bury this under a layer of context that engineers don't need, requirements that are actually design decisions, and success metrics that are listed but not prioritized.
A PRD that works:
- Problem (not the feature): What's broken for the user right now? One paragraph, specific, from the user's perspective.
- Success (in the user's words): What does the user experience after this ships that they can't experience today?
- Constraints (the real ones): What cannot change? What must be true? This is the box. Everything else is negotiable.
- The one thing we cannot get wrong: Name it. This is the decision that, if wrong, makes the whole thing wrong. Everything else is tradeoff.
- What's explicitly out of scope: As important as what's in. Stops the scope creep conversations before they start.
Anything not answerable by one of these questions might not belong in the PRD.
The Design Doc
Design docs exist so that people can challenge your approach before you've built it. They only work if they make your actual decision visible enough to be challenged.
Most design docs are good at presenting options and weak at presenting the recommendation. They describe three approaches neutrally and trust the reader to figure out which one the author prefers.
Name the recommendation explicitly. Put it at the top. Then describe the alternatives and why they lose. The reader's job is to find the flaw in your reasoning — make the reasoning visible enough to find.
Structure that works:
- Context (one paragraph — the reader should already know most of this)
- The decision (what you're recommending and the one-sentence reason)
- Alternatives considered (named, described, and explicitly rejected with reasons)
- Tradeoffs of the recommended approach (not hidden — stated plainly)
- Open questions (things you're still uncertain about that might change the answer)
The Decision Memo
When you need a decision from leadership, most people write a memo that presents information and implicitly asks the reader to do the work of forming a recommendation.
Don't make them do that work. Do it yourself.
Structure: Recommendation first. Rationale second. What you need from them, specifically.
"We should do X. Here's why. I need you to approve [specific thing] by [date] so [engineering/team] can proceed."
Every word in a decision memo should serve one of those three purposes.
The Async Update
The weekly update or project status that nobody reads has a specific failure mode: it's structured around what happened, not why it matters.
A list of completed tasks tells the reader what was done. It does not tell them what they should do with that information.
Structure that gets read:
- Status in one line: "On track / At risk / Blocked — [one reason why]"
- The one thing that changed this week that changes what you need to know
- What you need, if anything: A decision, a resource, an introduction
- What's next: One sentence on what happens between now and the next update
The reader is scanning for surprises and asks. Give them those things first.
The Slack Message
Slack messages have a specific writing failure mode that is different from documents: they are optimized for the writer's convenience and not the reader's.
"Hey, do you have a minute?" has a 50% chance of triggering a response that opens a five-message thread to get to the actual question. The reader is now context-switching across a conversation when they could have gotten the full information upfront.
Write Slack messages the way you'd write an email to someone's boss: complete, clear, and actionable.
"Hey — quick question on the auth service timeout. We're seeing intermittent failures in staging that look like it's hitting the 30s limit. Before I push a fix that bumps it to 60s, wanted to check if there's context I'm missing on why it's set where it is. Fine to handle async — no urgency."
That message has the context, the question, the proposed action, and the priority signal. The reader can respond with a sentence or ignore it until they're ready. No back-and-forth required.
The Complexity Tax
Every technical term, every acronym, every piece of jargon carries a cost. The reader has to decode it before they can receive the information. Some of that cost is necessary — there is no simpler way to say "idempotent" in some contexts. Most of it is optional.
The complexity tax matters because attention is finite. Every decode operation costs a small amount of the reader's working memory. Enough of them and the reader gives up — not consciously, but they start skimming, and they miss the thing you most needed them to catch.
This is particularly acute when writing across levels. An engineer writing for an executive, or a PM writing for a board, or a technical lead writing for a cross-functional team. The specialized vocabulary that is frictionless among peers is a translation problem for anyone outside that peer group.
The test: read the sentence without the technical term. If it's meaningfully less precise, keep the term. If it's equally clear, remove it.
The Edit That Matters Most
After you've written something, before you send it: read it as the person who will receive it.
Not you, not your expertise, not your context. Them, with their job, their time pressure, their prior knowledge.
Ask: where does this drag? Where does it assume context I haven't given? Where does it bury the point? Where does it make me do work you should have done for me?
Most of the answers will be uncomfortable, because they require cutting things you worked hard to write. That is precisely the edit that matters.
Good writing is not a record of good thinking. It is good thinking that has been translated into a form the reader can use. The translation is the work. Most people skip it.
What This Actually Changes
When engineers write clearly, code reviews are shorter. Design decisions get challenged earlier, when changing course is cheap. Onboarding is faster. Context lives in documents, not in people's heads.
When PMs write clearly, engineers ask fewer questions, make fewer wrong assumptions, and build closer to what was intended. Stakeholder decisions happen faster. Projects derail less often because the problems surface in writing before they surface in production.
Clear writing is not a soft skill. It is leverage. Every document you write is either compressing the time between thinking and action — or adding friction to it.
The engineering team that writes well ships faster. Not because writing is fast, but because the things that slow shipping — misalignment, rework, ambiguity, unnecessary meetings — are downstream of the same problem that bad writing is downstream of: unclear thinking, poorly communicated.
Writing isn't a report on your work. It is the work.
Start with the sentence: "After reading this, I need [specific person] to [specific action or understanding]." If you can't write that sentence, you're not ready to write the document.