Write What Matters (#8)
Don't Just Write What was Asked
I had nothing left.
I’d rewritten the intro four times.
And yet — there I was. Still poking at phrasing. Still reworking the same sentence. Still chasing 2% more clarity from a doc that was probably already good enough.
Was this iteration? Or inertia?
Without clear direction from the PM, I gave up. I submitted the draft.
Later, she messaged me: "Yeah, this is accurate and well-written… but now that I see it, it’s not what I want."
I replied, "Okay. Let’s use this as a reference to figure out what you do want."
She hesitated, then typed: "I want the doc to explain everything the feature does — just not in a way that overwhelms people. I want them to say wow, not oh shit."
I wrote back: "Okay — what if we lead with the benefits, keep the intro strong, and simplify the rest? Drop the heavy technical stuff, but include a callout for advanced users who want to dive into the JavaScript library? That way, it’s conceptual and friendly — but there’s still a path for power users."
She replied: "YES. That’s it.”
Discernment is the Real Skill
This is the part of the job no one talks about.
Not formatting.
Not syntax.
Not whether to capitalize “API.”
Good judgment is looking at a wall of content, an incomplete brief, or a vague request and knowing where to begin. It’s separating the work that leads to clarity from the work that just creates motion.
Some writers polish sentences when the structure is broken. They revise wording instead of asking if the article is necessary. Sometimes the article needs less, not more. And at some point, you have to ask: “Will this actually help anyone?”
Skilled writers focus on what matters:
Cut 500 unnecessary words that serve their egos
Push back against stakeholders when volume overshadows value
Sense when a request masks strategic confusion
Hear what’s missing
This is trained judgment. It is built from exposure, precision, listening, pattern recognition, and the nerve to act before everything is certain.
We tend to treat this kind of judgment like a modern skill, shaped by Jira tickets and agile timelines.
But it’s not new.
It’s ancient.
Long before technical writers wrangled API guides, people were making high-stakes decisions with limited information and no margin for error.
Not Everyone Gets Stuck
There’s a pattern in ancient texts, mythology, and modern storytelling:
One character exhausts himself by solving the wrong problem.
Another walks in, sees clearly, cuts through it.
Simplicity as Strategy
Recall David of David and Goliath fame. When David arrives on the battlefield, the entire army is stuck. Goliath has issued a challenge. For forty days, no one has taken up the challenge. They are paralyzed. They are debating armor, strategizing weaponry, and evaluating size and strength.
David sees something else.
He doesn’t match Goliath’s scale. He doesn’t need to. While others prepare for combat, David opts for precision. He refuses the armor, bypasses the noise, and isolates the real problem: an exposed, slow giant who is vulnerable in exactly one place.
Where others saw a fight, he saw a flaw. And he trusted it.
David simplifies the conflict.
This is discernment.
Seeing Beyond the Claim
Or, look to Solomon.
Two women stand before the king. One child. Two motherhood claims. No witnesses. No proof. They plead for judgment.
Solomon calls for a sword.
"We’ll divide the child," he says. "Each of you will receive half."
The words hang in the air.
One woman breaks. She cries out. “Give her the child,” she says. “Just don’t kill him.”
The other agrees to the split. Her truth is revealed not by her words, but by what she’s willing to destroy.
That was the judgment.
Solomon didn't need to divide the child. He needed a tool to discern the truth.
When Discernment Breaks Down
It’s easy to admire discernment in hindsight, to see the clean judgment, the simple move, or the truth revealed in one decisive moment.
But in the moment? That’s harder.
Most of us don’t simplify the conflict. We get stuck inside it. This kind of judgment doesn’t usually fail with a loud crash. It slips quietly, subtly, in slow misallocations.
I opened this article with that story about rewriting an intro four times. That wasn’t rigor. That was fog. I kept polishing the language without understanding the purpose or the audience.
The Pareto Principle — the idea that 80% of outcomes come from 20% of causes — isn’t just a productivity trick. It’s a warning. Many of us spend most of our time on the wrong things. And the longer we circle around them, the harder it is to stop. The more we’ve poured in, the more we need the effort to mean something.
We saw this dynamic occur at a global scale during the pandemic.
A 2022 study on frozen goals looked at people whose ambitions were derailed by COVID — projects they couldn’t pursue, roles they couldn’t grow into, plans they had to abandon. But even when those goals became impossible, they didn’t disappear. People held on. Internally, emotionally, they stayed committed.
And because they couldn’t move forward — or let go — many suffered higher stress, lower motivation, and diminished well-being.
Clear thinking doesn’t always mean pushing harder. Sometimes it means letting go — especially of the work that has stopped serving the goal.
Building Discernment
Like any skill, discernment is earned. Slowly. Quietly. But it compounds.
Here’s how to start.
1. Zoom Out Before You Zoom In
Start with the impact. Before you write a sentence, ask the following questions:
What is the purpose?
Who needs this?
What happens if they don’t get this?
Your writing intent depends on answers to these questions. You need to understand the goals, consequences, and user stakes.
2. Find the Question Beneath the Request
Most documentation requests are lists of symptoms:
A PM who writes "just explain everything" may really mean, "I don’t know what matters".
An engineer who wants "just accuracy" might be asking, "Can you validate my thinking?".
A user asking for clarification may be struggling with a deeper product flaw.
You need to understand what the request is really about.
3. Focus Where Confusion Costs the Most
Prioritize what actually matters to the user.
As you write your documentation, look for the following things:
Places where users get blocked
Confusion that leads to mistakes
Wording that improves user outcomes
Place your greatest effort toward the greatest user challenges.
Limits of Judgment
Discernment is valuable — but not invincible. It can isolate you, stall progress, or misalign you from the system you're trying to support. Most often, it backfires in three ways: replacing alignment with autonomy, showing up too early, or opposing scale.
The first risk is acting alone. Confident judgment can tempt you to skip check-ins or stakeholder reviews. You fix what’s broken — but quietly. Even a good call can feel like a breach if no one saw it coming. Quiet decisions, even correct ones, can erode trust.
The second risk is thinking too critically too soon. Writers stall when they try to refine structure before the content exists. Instead of getting ideas down, they second-guess everything. Early on, forward motion matters more than clarity. Overthinking creates drag.
The third risk is breaking the system to improve the doc. You might see a sharper structure — but if the doc sits inside a standard pattern, that change may create confusion, not clarity. This isn’t about copy. It’s about form. In scaled systems, consistency often wins.
This skill is still worth building. But it demands timing and restraint. You don’t just need the right answer — you need the right moment to act.
Choosing What Lasts
Discernment isn’t a nice-to-have. It’s the line between useful and wasted work.
Without it, you’ll keep rewriting introductions no one remembers and polishing phrases that don't matter. You'll miss what your users actually need because you were too busy perfecting what they don’t need.
The discipline is this:
Pause before the draft
Dig into the request
Hear what’s behind the ask
Act with judgment
This is the job: write what matters.