Clarity: The Core Skill
What Clarity Means
Clarity is the property of being understood on the first read by the intended reader.
That's a modest-sounding definition. It's also rarer than you'd think. Most work writing is understood in a second or third read, or half-understood, or understood differently by different readers, which leads to half the meetings you've ever been in.
Unclear writing is expensive: every reader spends extra time decoding, and some of them end up with a different interpretation. Clarity is not a nice-to-have stylistic virtue. It's the output measure of operational writing.
The Five Properties of Clear Writing
Concrete names, numbers, specifics; not vibes
Self-contained a reader landing cold can follow
Ordered the sequence matches how a reader will process
Minimal no filler; every sentence earns its place
Visible the structure shows (headings, lists, emphasis)
Each is independent. Clear writing exhibits all five. Most drafts fail at two or three and can be improved by targeting those specifically.
Concrete Over Vague
The single most common clarity problem: abstract language where concrete language was possible.
Compare:
Vague: "We should probably think about improving the performance of our system."
Concrete: "The checkout page takes 4 seconds to load. We should target under 1.5s by Q3."
The vague version is wallpaper: it could describe almost any situation. The concrete one is specific enough to act on.
Concrete writing contains:
- Names: of people, products, features, files
- Numbers: times, counts, ratios, deadlines
- Dates: not "soon" but "by April 30"
- Examples: "like X" or "similar to when Y happened"
- Specific verbs: "migrate", "replace", "measure", not "optimise", "improve", "enhance"
Why writers default to vague
Three reasons:
- Lack of information. Sometimes you genuinely don't know the specifics. Say that explicitly: "We don't yet know the exact slowdown; rough estimate is 3-5 seconds"
- Fear of being pinned down. Vague language is a hedge against being wrong. Usually the cost of vagueness exceeds the cost of being specifically wrong
- Habit. Business writing is saturated with abstractions. Undoing the habit is a long project
A test
Read your draft. For every noun, ask: can this be more specific? For every verb, ask: is there a more precise one?
Often you'll find whole sentences that vanish when examined: they were abstract noise.
Self-Contained
A piece of writing is self-contained if a reader landing cold can follow it.
This is a surprisingly high bar. Writers tend to assume the reader shares context they have. They don't. A doc about "the migration" is unclear; a doc about "the migration from Postgres 14 to Postgres 16 scheduled for April 29" is not.
How to check
Imagine a new hire reading your piece on their first day. They know basic domain vocabulary but nothing about your team's history. Can they follow?
- Does the piece define its key terms (or link to definitions)?
- Is the context clear, or is it "as we discussed"?
- Are the people, products, and systems named clearly?
- Is the question the piece is answering articulated, or do you have to infer?
You won't always write for this hypothetical new hire. But checking against them reveals where your writing depends on unstated context.
Links and references as self-containment aids
You don't have to pack every detail into every document. Link out:
- "See the architecture doc at /wiki/arch-2026"
- "This follows the earlier discussion in ticket #447"
- "For the full spec, see [link]"
Links let a reader fill in context if they need to, without cluttering the main doc. Use them generously.
Ordered Appropriately
Information has a natural order given the reader's purpose. Writing that ignores this order is harder to follow even if every individual sentence is clear.
The most common error: chronological order, when the reader doesn't care when things happened. A bug report that tells the story in the order the author experienced it is less useful than one that leads with "the symptom" and "the cause", then explains how that was discovered.
Common useful orders:
Most-important-first (inverted pyramid)
For most work writing:
- The main point / decision / ask
- Key supporting context
- Details for readers who want them
- Edge cases and footnotes
A reader can stop at any point and still have the gist. This is the dominant shape of effective memos, PR descriptions, and tickets.
Reader's discovery order
For docs and tutorials:
- What is this?
- Who is it for?
- How do you start?
- What can you do next?
- How does it work under the hood?
Matches how a new reader actually encounters the topic.
Problem → solution
For bug reports, proposals, and postmortems:
- What's wrong / what we need
- What we propose
- Why this over alternatives
- Implementation / next steps
Chronological
Only for actual narratives (incident timelines, project histories, retrospectives). Otherwise, restructure.
Minimal
Every sentence earns its place. Every word too.
This is the hardest to do well and the most rewarding when done. Minimal writing feels effortless to read; the effort was in the cutting.
Common filler to watch for:
Wind-up phrases
"In order to..." just "to"
"It is worth noting that..." cut; write the thing directly
"I just wanted to say..." cut the wind-up; say the thing
"There are X that..." rephrase with X as the subject
Hedges
"might possibly" "might"
"could potentially" "could"
"quite" often just cut
"really" often just cut
"very" often replaceable by a stronger adjective
Abstractions that add no information
"leverage synergies to..." almost always cut or rewrite
"drive alignment on..." "agree on..."
"on a go-forward basis" "from now on"
"at the end of the day" cut
Doubled words
"first and foremost" pick one
"each and every" pick one
"due to the fact that" "because"
The pass test
Read each paragraph. Cross out anything that adds no information. If the paragraph still makes sense, those words were fluff. Delete them in the real draft.
Most first drafts lose 20-40% of their words to this pass without losing any meaning. Some lose more.
Visible Structure
Reading is partly a navigation task. Readers should be able to see the shape of your document, skim it, and find what they need.
Visible structure looks like:
- Headings that describe sections, not vague labels
- Lists for items that are actually items (options, steps, properties)
- Short paragraphs that each make one point
- Emphasis (bold, occasional italics) to mark what's important
- Code blocks for code, commands, filenames, and quoted output
- Whitespace between sections
Headings as an outline
Good headings let a reader skim the doc and understand the shape. Bad headings (generic "Overview", "Details", "Other") tell the reader nothing.
Bad headings:
- Overview
- Background
- Details
- Conclusion
Good headings:
- The problem with the current checkout flow
- Proposed change: a single-page checkout
- Tradeoffs and mitigations
- Implementation plan
The good headings tell the reader what's inside before they read.
Lists vs paragraphs
Use lists for items that are discrete. Use paragraphs for arguments or narratives.
List works: steps, options, criteria, features, risks
Paragraph works: arguments, explanations, stories, transitions
Not every document needs lists. Not every document needs paragraphs. Use each for what it's good for.
Formatting restraint
Every formatting device you use dilutes the ones you use less. If everything is bold, nothing is. If every paragraph has emphasis, none stand out.
Use formatting sparingly. A single bold phrase in a document draws the eye; three bold phrases compete; ten make the page unreadable.
The Clarity Pass
After a first draft, run a specific clarity pass. In order:
- Identify the primary reader. If you can't, the clarity problem is upstream of the writing
- Move the most important content to the top. Usually requires some cutting
- Replace vague language with concrete. Names, numbers, dates, examples
- Cut filler. Wind-ups, hedges, doubled words, padding
- Add structure. Headings, lists, formatting for scanning
A clarity pass usually takes half the time of the original draft and roughly doubles the effectiveness.
When Clarity Is Hard
Some topics resist clarity:
- Genuinely complex technical material. Not every concept simplifies
- Political or sensitive topics. Diplomatic language has purposes clarity lacks
- Emerging ideas. The first articulation of a new thought is rarely clean; clarity comes in revision
- Legal and regulated writing. Has its own rules
For most of these, the answer is not "abandon clarity" but "be as clear as the topic allows, no more vague than necessary". Diplomatic language is less clear by design; it shouldn't be more diplomatic than it needs to be.
The Clarity Virtue Is Boring
A closing note: clarity is not a glamorous skill. Elegant sentences, surprising turns, distinctive voice are more fun to notice. Clarity is the skill that makes work-writing effective whether or not anyone compliments it.
Most readers won't thank you for clarity. They'll just do what the document asked, or understand the proposal, or find the bug faster. That is the measure. Compliments are rare; outcomes are what matter.
Common Pitfalls
"Being clear means being simple." They aren't the same. Clear writing can address complex topics. Simplification without precision isn't clarity; it's omission
"I'll make it clear in the second draft." Usually true for structure; often not for clarity of thinking. Getting clear in your first-draft sentences keeps the writing honest throughout
"Vague wording is more polite." Sometimes. Often it reads as weasel and creates more confusion, which is its own kind of rude
"My topic is too complex for clarity." Usually overstated. The reader doesn't need the full complexity; they need the specific slice you're communicating
"I know what I mean; that's what matters." No. What matters is whether the reader knows what you mean. Writing's job is to transmit, not to confirm
Next Steps
Continue to 04-writing-as-thinking.md for how writing clearly changes what you can think.