Writing for Async Teams: Memos, Docs, PRs, Tickets

The Async Premise

Async teams coordinate through writing because the alternative (meetings for every decision) doesn't scale and loses to time zones.

Good async writing:

• Self-contained: reader doesn't need other context
• Searchable: findable later by the next person with the same question
• Time-independent: still useful a week later, a month later, a year later
• Decision-supporting: makes it possible to act without needing to ask more

Bad async writing requires follow-up: questions in Slack, meetings to clarify, private DMs for context that should have been in the doc. Every follow-up is a cost the original document could have prevented.

The Five Common Forms

Most async team writing falls into five forms. Each has its own shape:

Memo           proposes or argues (a decision, a direction, a critique)
Doc            teaches or references (how this works, how to use it)
PR description a specific code change, its why, its how to test
Ticket         a problem or task for someone to do
Update         status: what happened, what's next

Slack, email, meeting notes, and a dozen other forms are variations of these.

Memos

A memo argues or proposes. Decision memos are the workhorse of async teams.

Structure that works

1. TL;DR (2-3 sentences)
2. Context: what's the situation, why are we addressing it
3. Proposal: what you recommend
4. Alternatives considered: what you weighed, why not them
5. Tradeoffs: what this costs
6. Asks / next steps: what you need from the reader

Length: whatever the topic needs. A two-page memo is often better than a five-pager on the same topic. A five-pager is often better than a twenty-minute meeting.

Why TL;DR first

Most readers won't read the whole memo. They'll read the TL;DR and skim the rest. The TL;DR should stand alone: if the reader only reads those three sentences, they should know what you're recommending and what you need.

The Amazon six-pager

Amazon's best-known cultural practice: for important decisions, the team produces a six-page narrative memo. The meeting starts with silent reading for 15-20 minutes, then discussion.

Two effects:

1. The author had to think carefully. A memo can't hide behind a slide's visual authority; the argument is exposed
2. The group considers the actual argument, not the presenter's charisma

Most teams aren't Amazon. Many can steal pieces of this culture: the memo-before-meeting pattern works for most substantive decisions, whether the memo is two pages or six.

Docs

A doc teaches or references. Two flavours:

Teaching docs

Guides, tutorials, onboarding material. The reader doesn't know the topic yet. The doc's job is to build their understanding efficiently.

Shape:

1. What this is
2. Who it's for
3. Prerequisites (if any)
4. The core content, ordered from simple to complex
5. Next steps or further reading

Examples of good teaching docs in software: the Django tutorial, the Stripe API docs, Tailwind CSS's getting-started pages.

Reference docs

API references, configuration options, command lists. The reader knows the topic; they need to look something up.

Shape:

1. Quick index or table of contents
2. One entry per thing being documented
3. Each entry: name, signature, description, example, notes
4. Cross-references to related entries

Reference docs live in the format. The reader is scanning; visibility is everything. Headings, code blocks, tables, consistent structure.

Reference docs are where the language-tag-every-code-block habit pays off most visibly.

Keeping docs alive

The biggest doc problem isn't writing them; it's keeping them current. Some patterns that help:

• Code in docs: test the code blocks, so out-of-date ones get caught
• Ownership: every significant doc has an owner who checks it quarterly
• Last-reviewed dates: let readers see when a doc was last updated
• Change logs: for docs that have substantially evolved

Stale docs are worse than missing docs: a new hire who reads outdated docs gets confidently wrong information.

PR Descriptions

Pull request (or merge request, code review) descriptions are the writing engineers do most often. Many do it badly, and the cost is paid in review rounds and merged bugs.

Shape that works

1. What this does (1-2 lines)
2. Why (link to ticket or explain briefly)
3. Approach: the core idea of the change (if non-obvious)
4. Tradeoffs or alternatives considered (if any)
5. Test plan: how you verified it works
6. Screenshots / examples (for UI or output changes)
7. Follow-ups: things this PR does NOT do

Not all PRs need all sections. A one-line typo fix can have a one-line description. A 500-line refactor benefits from every section.

What reviewers need

A reviewer is context-switching into your change. They know less than you about it, probably less than you think.

• Why are we making this change?
• What's the smallest thing that would convince me it works?
• Where should I look first?

A good description answers these before the reviewer has to ask.

What reviewers don't need

• A file-by-file walk-through of the diff (the diff shows that)
• Overuse of "I" and personal narrative ("I was reading through the code...")
• A history of everything you tried before landing on this approach

Those can go in comments on specific lines if relevant.

Tickets

A ticket describes a unit of work. Someone will read it and do the work; the ticket determines whether they do the right thing.

Shape that works

For a bug:

1. Summary (one line)
2. Steps to reproduce
3. Expected behaviour
4. Actual behaviour
5. Environment (browser, version, etc.)
6. Severity / impact
7. Relevant logs or screenshots

For a feature:

1. Summary (one line, user-story shape often works: "as a X, I want Y so that Z")
2. Problem / context
3. Proposed solution (if clear)
4. Acceptance criteria
5. Out of scope (what this ticket does NOT cover)
6. Links to related tickets, designs, or discussions

Common ticket failures

• Summary that's too vague. "Fix the checkout" is not actionable; "Checkout page shows incorrect total when coupon is applied twice" is
• No acceptance criteria. Engineer doesn't know when they're done
• Scope creep in the comments. Additional requirements pile up in comments; ticket's real scope diverges from its title
• Decision history as scattered comments. Important context in comment #47 instead of the body

The body should be the source of truth. Update it as the ticket evolves.

Status Updates

A weekly update (or standup note) tells the team what you did and what's next. Most are bad because they're phoned in.

Shape that works

1. What I completed this period
2. What I'm working on this period
3. Blockers or asks
4. Notable wins or learnings (optional)

Three sections. Five to ten bullet points total. Reading the update should take less than a minute.

Common update failures

• Narrative mode. "On Monday I... then Tuesday I..." No one needs the timeline
• False completeness. Listing every tiny action to look busy. Salient items only
• Vague completion claims. "Worked on the dashboard" vs "Shipped the dashboard's v1 to staging; waiting on design feedback"
• No asks. Many updates need something; hiding it is a mistake

For managers

If you're a manager writing an update for your team, the shape is slightly different: more emphasis on what's happening across the team, what's decided, what's coming. Your update is a small newsletter to your team, not a log of your individual activity.

Meeting Notes as Artefacts

A durable practice: every meeting produces a note that's useful to people who weren't there.

Good meeting notes:

• Start with a one-line summary of the decision or outcome
• List specific decisions (not discussions; decisions)
• List action items with owner and deadline
• Capture open questions for follow-up
• Link to the original agenda and any docs discussed

Bad meeting notes are transcripts: "Alice said... then Bob said..." That's archival, not actionable.

If no one's going to read the notes, don't write them. If they're going to be read, make them compressed and useful.

The Anti-Patterns

The wall of text

A paragraph that runs for half a page. Almost never worth it in async. Break into shorter paragraphs, lists, or sections.

The bury-the-lead opening

"Hey team, I hope you're all doing well. Last week we had a discussion about..." Cut to the point in the first sentence.

The passive voice escape hatch

"A decision was made to..." Who made it? Say who. Passive voice in decision docs is often hiding agency.

The "just wondering" ask

Disguising a real request as a question. "Just wondering if we could move this deadline?" is either a question or a request; pick one. Direct asks get better responses than disguised ones.

The unread attachment

A three-page doc attached to a Slack message with no summary. The recipient has to decide whether to open it, with no signal. Always summarise before attaching; make it easy to read the attachment for the right reader and skip it for the wrong one.

The performance-review doc

A memo written for your reviewer's eyes as much as for the decision. These have tells: excessive hedging, credit claims, political carefulness. Usually better to separate: write the real memo, and write a separate reflection if needed.

A Closing Note on Slack

Slack is writing too, and it deserves attention:

• Short messages per message. Cut the "Hi!" wait-for-response. Ask the question
• Threads for side conversations. Top-level gets crowded otherwise
• Mention specifically. @here is a siren; use it for things that actually need everyone now
• Bold the action. In a long message, bolding the ask makes it scannable
• Async-compatible. Don't expect an answer in 3 minutes unless the urgency is real

Most Slack channels would be better with 30% less volume. The things written are less the problem than the things said that didn't need saying.

Common Pitfalls

"I'll just send a quick Slack message." Quick Slacks often replace docs that should have been written. Every decision spread across 14 Slack messages is a doc no one will be able to reconstruct

"The template is too rigid." Templates are starting points. Adapt them. But "the template is too rigid" is often an excuse to skip the structure that would have helped

"Long docs don't get read." Badly structured docs don't get read. A well-structured 6-page memo with a good TL;DR gets more reading than a 2-page wall of text

"We don't need docs; we talk enough." If you can afford to talk enough, you don't have an async team. Most companies can't afford it at any scale. Docs are the default, conversations the supplement

"Writing is slow." Bad writing is slow. Good async writing pays back within a week in clarification saved. Writing is an investment, not a cost

Next Steps

Continue to 06-writing-for-ai.md for the writing that makes AI tools actually useful.