Stop 05 · Requirements & DocumentationTopics · 9/9

Writing for Engineers vs Executives

In short

The same update needs two very different versions. Engineers want details to build with. Executives want the decision and the risk in thirty seconds.

The same feature needs two different documents — engineers need precision, edge cases and detail; executives need the headline, the 'why', and the business impact in three sentences.

The purple blob talks to a friend holding a textbook on one side and to smiling parents on the other.

Think of it like this

Telling two people about your exam

With your batchmate, you go question by question: which ones were tricky, where you lost marks. With your parents, it's one line: passed, good rank, one subject to improve. Same exam, different listener.

Watch it happen

One launch delay, two messages

To engineers

Exact cause and affected services
Edge cases and open questions
Links to tickets, logs, designs

To executives

Headline first: delayed one week
Impact on goals and customers
Decision needed, with your recommendation

Know your reader. Put what they need to act on first, and link to details for anyone who wants more.

The big ideas

What you need to know

Executives: bottom line up front

Start with the conclusion or ask. Context comes after, if at all.

Engineers: precise and complete

Clear rules, states and constraints. Ambiguity costs them hours.

Always name the risk

Both audiences need to know what could go wrong, just at different levels of detail.

Cut ruthlessly

Read it as your audience would. Remove anything they won't use.

Save yourself the pain

Common mistakes

Oops

Sending executives a long story that ends with the actual news.

Do this instead

Put the news and any decision needed in the first two lines.

Oops

Giving engineers a vague summary like "improve checkout".

Do this instead

Give the specific problem, constraints, acceptance criteria and links.

Your mission

Write one update two ways

~20 min

Quick check

What should the first line of an update to an executive usually contain?

Go deeper

1Take one feature idea and write both a 3-sentence exec summary and a detailed spec.
2Learn the 'inverted pyramid' style: lead with the conclusion, then the detail.
3Practice cutting your exec summary down until only the essential remains.