✍️ English & Grammar · Chapter 8

Writing a status update people read

Your manager reads your update on a phone, between meetings, in about twelve seconds. Write for those twelve seconds.

Study this lesson free in the app →

The basics

A status update is a short, regular written note — weekly email, Slack post, standup message — telling people who depend on your work where it stands.

The problem it solves: your manager reads it on a phone, between meetings, in about twelve seconds, and may forward it to a director who reads one line. An update that lists effort ("worked on the pipeline, had discussions") leaves them knowing nothing they can act on — and when the project slips, it proves nobody saw it coming.

The mental model: a newspaper front page. The headline states the outcome; detail thins out as you go down, so stopping early still leaves the reader informed. Engineers naturally write in solving order (context → investigation → finding). Reporting needs the reverse.

The shape: status line → Done (with numbers) → Next (with dates) → Need from you → Detail.

Explained

"This week I worked on the pipeline. I was looking into some issues with the Kafka consumer and also had discussions with the platform team. I am still working on the dedup logic. Additionally I attended the design review and did some analysis on the storage costs. Will continue next week."

Everything in that paragraph is true, and after reading it your manager knows nothing they can act on.

Not one number. Nothing finished. No problem raised. No decision requested. Nine days later, when the project slips, this update will be evidence that nobody saw it coming.

The newspaper front page

A newspaper never opens with background. The headline states the outcome, the first paragraph gives the essentials, and the detail thins out as you go down.

That structure exists because most readers stop early — and it's designed so that stopping early still leaves you informed.

Engineers write the opposite way, because that's how we think: context, investigation, then finally the finding. It's the right order for solving a problem and the wrong order for reporting one.

Put the finding first. Anyone who wants the reasoning will read on; anyone who stops after one line still leaves with the thing that mattered.

The shape of a readable update

BLUF — bottom line up front. If the reader stops after line one, they should still know whether to worry.

The three habits that do the work

1. Lead with status, not activity.

✗ This week I worked on the dedup logic.
✓ Dedup is done and deployed; revenue now reconciles to 0.02%.
✓ Dedup is at risk — I need a decision on the tie-break rule by Wednesday.

Worked on describes effort. Your manager is not buying effort.

2. Replace adjectives with numbers.

✗ Made good progress on performance.
✓ Query time down from 47s to 6s on the daily mart.
✗ Fixed a lot of data quality issues.
✓ Rejected records fell from 4.1% to 0.3% after the schema fix.

A number is checkable, comparable and memorable. An adjective is none of those, and it quietly reads as nothing measurable happened.

3. Separate done from in-progress, ruthlessly.

If it isn't merged and running, it isn't done. "Almost done" for three weeks running is the single most common warning sign in engineering reporting, and everyone senior has learned to hear it.

The same week, rewritten

**Rides pipeline — on track, one decision needed**

**Done**
- Dedup on event_id shipped Tuesday. Friday's revenue now reconciles
  with the payment provider to 0.02% (was 2.4% over).
- Storage analysis: raw pings are ~2 TB/yr compressed. Downsampling
  after 30 days would cut long-term storage ~90%.

**Next (by 8 Aug)**
- Backfill the last 19 days with the corrected dedup.
- Draft the retention proposal for the downsampling change.

**Need from you**
- Decision on the tie-break when two events share an event_id but
  differ in fare. I've assumed "keep the later one"; if finance needs
  something else, I'd rather change it before the backfill runs Thursday.

**Detail**
- Root cause was Kafka at-least-once retries being counted twice.
  Writeup in DATA-412.
- Platform team confirmed we can raise retention to 7 days at no cost.

Same week's work. The manager can now act on it in twelve seconds: something shipped with a number attached, there's a dated plan, and there is one specific decision with a deadline and a stated default.

Which line survives?

A manager forwards your update to their director, who reads only the first line.

Which of these first lines actually does its job?

A. "This week I continued working on the ingestion pipeline and related tasks." B. "Rides pipeline: on track. Dedup shipped, revenue now reconciles to 0.02%." C. "Had a productive week on several fronts, details below." D. "Rides pipeline: BLOCKED on the finance decision since Monday — slipping ~3 days per day of delay."

Why the boring one gets the credit

Two engineers do comparable work over six months.

One writes: "Worked on data quality improvements."

The other writes: "Rejected records down from 4.1% to 0.3%. Finance stopped filing reconciliation tickets — that was ~6 hours a month of their time."

At review time, the second engineer's manager has six months of specific, quantified outcomes to argue with. The first has an impression of someone busy.

This isn't about self-promotion. Your manager is advocating for you in rooms you're not in, and they can only carry what you gave them. Vague updates leave them defending you with adjectives against colleagues arriving with numbers.

The practical version: keep a running file. Every time something ships, write one line with a number in it. It takes fifteen seconds, and it turns the review-time question "what did I actually do this year?" — which nobody can answer honestly from memory — into copy-paste.

Bottom line up front. Status in line one, so stopping there still informs.

Numbers, not adjectives. "Good progress" says nothing; "47s → 6s" says everything.

Blockers early and costed — bad news is forgivable when it arrives in time to act on.

Words to know

In two minutes

• Write for a reader with twelve seconds on a phone who may forward only your first line.
• Bottom line up front: on track, at risk or blocked — before any context.
• Report outcomes, not effort: 'shipped, metric A → B', never 'worked on'.
• Replace adjectives with numbers; a number is checkable, an adjective reads as nothing measurable happened.
• Done means merged and running; 'almost done' twice in a row is the classic warning sign.
• Raise blockers early, sized, with a deadline and a proposed default.
• Your manager advocates for you with your own words — keep a running file of shipped outcomes with numbers.

Test yourself

There are 11 questions, 3 puzzles and 7 recall cards for this lesson in the app — the recall cards come back on later days, just before you would forget.