Guide

Working with people

Writing for skimmers

Assume a tired reader on a phone. Headings that say something, one idea per paragraph, links instead of dumps.

85 of 166 · 2 min read

Most of your readers will not read you. They will scan for a decision, a date, an owner or a risk, then leave. Writing for skimmers means you design for that scan, not for a quiet evening with your prose.

Concept

A skimmer is a tired, interrupted reader — often on a phone — who will give you two lines and a glance at headings. If those do not carry the point, the point is lost. Start from BLUF.

The big idea

Paper essays reward a rising argument. Chat and docs reward a table of contents that works even if nobody opens a section. Structure is the product; sentences are the filling.

A useful picture: airport signage. "Gates 40–55 →" beats a paragraph about concourse layout. The picture breaks for a design doc that must teach a mechanism — but even there, headings should name the finding, not "Background."

Walking through it

Assume the reader is tired. Then:

  1. One idea per paragraph. Short paragraphs. A wall of text is a skip signal.
  2. Headings that say something. Prefer "Latency cause: DB connection pool" over "Background".
  3. Bullets for lists of facts. Numbers, owners, dates, links.
  4. Bold sparingly for the one phrase a skimmer must not miss (the decision, the deadline, the severity).
  5. Links, not paste dumps. Point to the doc, dashboard or PR; quote only the two lines that matter.

Edit in a second pass. First drafts are for you; second drafts are for them.

  1. Cut. Remove "I just wanted to reach out," hedges you do not mean ("sort of", "maybe we could potentially") and duplicate sentences.
  2. Concrete. Replace "improved performance" with "p99 latency 800 ms → 120 ms on checkout." Replace "soon" with a date.
  3. Active voice. "We deployed the fix" beats "The fix was deployed." Name the actor when accountability matters.
  4. Verbs over nouns. "Decide" beats "make a decision."
  5. Read aloud the first three sentences. If you lose the point, rewrite.

Google's technical writing courses and Paul Graham's "Write Simply" are the same move at different scales: if you cannot say it plainly, you may not yet understand it.

Keep a swipe file: three of your best updates, one decision request, one calm incident note. When you are tired, copy the shape.

Common mistakes

  • Mystery-novel structure. The point arrives in paragraph four. Put it in line one, then support it.
  • Heading theater. "Update", "Thoughts", "FYI" tell a skimmer nothing.
  • Paste dumps in Slack. Forty lines in a busy channel. Use a parent headline, a thread and a doc link.

Check yourself

  1. Which heading helps a skimmer more: "Background" or "Why Friday is at risk"?

"Why Friday is at risk" — it names the finding. "Background" is a skip.

  1. You wrote "we improved performance recently." What do you change?

A number and a date: "checkout p99 800 ms → 120 ms on 12 Mar."

Key takeaways

  • Design for a two-line scan: informative headings, short paragraphs, bullets for facts.
  • Edit for length, concreteness and active voice before you send.
  • Link the artifact; do not paste it.

Further learning

Technical Writing courses (Google)Technical Writing Courses for EngineersGoogle for Developers Write Simply (Paul Graham)Write Simplypaulgraham.com

Next: status and decision updates.

Bottom line up front

Put the decision, ask or outcome in the first sentence. Context comes after.

Written and verbal communication

Lead with the point, write for skimmers, and adjust depth for engineers, PMs and executives.

Status and decision updates

Shared templates for status, incidents and decision requests so readers know where to look.