Studies中文EN

Based on classic texts from open-source communitiesA Guide to Collaborative Communication

What we stand forEvery message lets the reader act as soon as they finish it: state the conclusion, the basis, the next step with a date, and who needs to do what

Part 1

A model of collaboration

Goals, information, decisions, communication, attention and trust, and four corollaries that follow

Part 2

Classic texts

A dozen texts left by open-source communities and remote teams, and what each one argues

Part 3

What we do

One case, the four parts of a message, six common situations

XingHuaTranslated from the Chinese edition
16 slidesAll examples are fictional

Part 1 · A model of collaboration

Start with one person: under a goal, information drives decisions, and decisions drive results

Informationwhat I know Decisionwhich option Actiondo it Resultthe status changes Goalwhat is good
  1. 1A decision depends on the goal and the informationThe goal defines what counts as good; information determines how well you can choose. Everyone picks what looks best to them, given their own goal and the information they have.
  2. 2Results are uncertainA good decision does not guarantee a good result every time, but over the long run the quality of decisions determines the quality of results.
  3. 3Results become new informationAfter one round the status has changed, and the next decision starts from the new status. The faster the loop turns, the faster you correct course.

Part 1 · A model of collaboration

Collaboration is many loops linked together: goals must align, information is dispersed, attention is limited

Communication: information flows between peopleTogether: the shared goal Writes the planInformationDecisionActionResult Builds itInformationDecisionActionResult Talks to usersInformationDecisionActionResult Each person holds only their own part; my decision needs information that you holdMy result changes your status; the parts add up to the overall result
  1. GoalThe result everyone wants together. Only with aligned goals do the parts decide in the same direction
  2. Information and decisionsInformation is dispersed across people; each decides on what they hold
  3. CommunicationThe channel through which information flows between people
  4. AttentionconstraintWriting and reading both cost attention, and everyone has only so much per day
  5. TruststateBuilt up over long collaboration; decides whether received information can be used directly

One proposition follows:Each decision is reasonable given that person's goal and information, yet the decisions may not fit together. For the overall result to approach the optimum, goals must align, information must arrive, and it should cost as little attention as possible.

Part 1 · A model of collaboration

Communication runs in two directions, giving and asking, and both carry status, judgment and expectation

Before: each person holds only the information of their own part

Writes the plan

Information

Plan

Decision

Sets scope on an assumed timeline

Builds it

Information

Build

Decision

Schedules on their own reading of the scope

Talks to users

Information

Users

Decision

Answers users with an estimated date

ResultEach decision is reasonable on its own information; together they do not fit

Three kinds of information

Statusfacts that have already happened
Judgmentmy interpretation and conclusion
Expectationwho does what next, by when, and the likely result
→

After: each gains the information relevant to their own decision

Writes the plan

Information

PlanBuildUsers

Decision

Sets scope on the real timeline

Builds it

Information

BuildPlan

Decision

Schedules on the confirmed scope

Talks to users

Information

UsersPlanBuild

Decision

Answers users with the confirmed date

ResultDecisions fit together; the overall result is closer to the optimum

Givesend over the information the other person needs to decide“Six of the eight design pages are done. I will post the full set in the channel by Friday 18:00.”
Askrequest the information my decision lacks, or ask the other person to act“Monday’s review needs the full set. Can you deliver by Friday?”

The purpose of communication: with as little attention as possible, give everyone involved more complete information and more consistent expectations, so that each decides on sufficient information and the overall result moves toward the optimum.

Part 1 · A model of collaboration

Trust is what accumulates as expectations are verified by results; it decides whether information can be used directly

Expectationthe other person tells me what will happen next
DecisionI plan my own work on that expectation
Resultwhat actually happened when it came due
Comparedoes the result match the expectation?
Trusthow predictable the other person is to me
Carried into the next round: can I decide directly on the expectations this person gives me?

How trust updates each round

Delivered on time↑ rises
Things changed, expectation updated before the date→ holds
The date passes in silence: an expectation gap↓ falls

As in markets, the expectation gap often matters most. When things change, update the expectation before the date, much as a listed company revises its guidance ahead of results.

With higher trust, what changes elsewhere in the model

InformationThe expectations you receive can be used as a basis for decisions without re-checking
CommunicationThe same decision needs less communication, saving attention on both sides
Decisions and resultsEveryone’s loop turns faster, and the overall result is closer to the optimum

Part 1 · A model of collaboration

Four corollaries follow from the model; the texts and practices that come next all derive from them

Model: a decision depends on the goal and the information

1

Give all the information the other person needs to decide

Whether giving or asking, state the status, your judgment and the expectation. Whatever is missing, the other person has to fill in alone.

Part 2: asking Part 3: four parts

Model: attention is a constraint

2

Put the conclusion first and say it once

The reader can use it after one read, without opening links, digging through history or asking again. The more readers, the more the writing time is worth.

Part 2: writing clearly Part 3: giving

Model: information is dispersed, and collaboration has many rounds

3

Write it down where everyone can see it

People who were absent, and people who join later, get the same information when they decide.

Part 2: moving work forward

Model: trust comes from expectations verified by results

4

Make expectations specific and update early

State the date and scope, then deliver. If things change, update the expectation before the date.

Part 3: giving

The model is now complete:under a shared goal, information drives decisions and decisions drive results; communication moves information between people, under the constraint of attention; trust decides whether that information can be used directly.

Part 2 · Classic texts

Classic texts from open-source communities and internet companies

The internet industry’s earliest collaboration happened on mailing lists and forums. The person asking and the person answering did not know each other, lived in different time zones, and the answerer had no obligation to reply. Whether you got help depended on how clearly one message was written. Remote teams later wrote the same practices into their company handbooks.

Reporting problemsAn open-source author writes down how to report a bug so that it gets fixed1999
AskingThe hacker community writes down how to ask so that someone answers2001
Conclusion firstA habit from consulting and US military writing becomes the norm in tech companies2000s
PostmortemsGoogle publishes its blameless postmortem method2016
Async workRemote teams publish their communication handbookslate 2010s

The next three slides introduce the texts under asking, writing clearly, and moving work forward.

Part 2 · Classic texts 1/3

Asking: five texts together describe the four segments of one question

A question that is easy to answer

Segment 1Greeting and question together

“Hi, one thing to confirm:”

Segment 2What I am trying to solve

“I want to …”

Segment 3What I have checked

“I read …, and tried …”

Segment 4My understanding. Is it right?

“My understanding is …. Is that right?”

No Hellonohello.netPut the greeting and the question in one message, so the reader can answer on sight.Don’t Ask to Askdontasktoask.comJust write the question; whoever knows will answer.
The XY Problemxyproblem.infoWhen you want to solve X, state X together with your attempted approach Y, so others can judge whether Y fits.
How To Ask Questions The Smart WayEric S. RaymondSearch and read the docs first; describe the symptoms and what you have tried; after it is solved, post a note on the outcome.
How to ask good questionsJulia EvansState your current understanding, then ask “is that right?”; ask questions that facts can answer.

Part 2 · Classic texts 2/3

Writing clearly: conclusion on top, facts at the base

Opening in four sentences: situation → complication → question → answer
SCQAhow to openFour sentences at the start tell the reader why this document exists.
Conclusionfirst sentence
BLUFBottom Line Up FrontPut the conclusion and the request in the first sentence; background and argument come after.
Argument 1 Argument 2 Argument 3grouped, one idea per group
The Pyramid PrincipleBarbara MintoConclusion first, then grouped arguments, then data. Wherever the reader stops, they leave with a complete idea.
Facts and datawhat you saw, what you expected, how to reproduce
How to Report Bugs EffectivelySimon TathamState what you saw, what you expected and how to reproduce it; keep facts and speculation apart.

Part 2 · Classic texts 3/3

Moving work forward: four texts map to four stages of one piece of work

Stage 1

Write it down, in the open

GitLab Handbook

Write it down and keep it as public as possible, so people who missed the discussion can still follow.

Stage 2

Read and reply in your own time

Basecamp: How We Communicate

Write complete thoughts in full paragraphs; do not expect immediate replies; meetings are the last resort.

Stage 3

Decide and execute

Amazon Leadership Principles

Own the work; act first and correct later; voice disagreement, then commit fully once decided.

Stage 4

Postmortems

Google SRE:Postmortem Culture

Blameless: impact, causes and action items, each with an owner and a date.

Action items from the postmortem are written down and enter the next round

Part 2 · Summary

The three premises these texts share are the model’s corollaries in other words

Premise 1 · Corollary 2

The reader’s time is worth more than the writer’s

Five more minutes of clear writing saves every reader one follow-up question.

Premise 2 · Corollary 3

Write it down where everyone can see it

People who were absent or join later can look it up. For a conclusion reached face to face, one written line is enough.

Premise 3 · Corollary 1

Every message moves one action forward

After reading, the reader knows two things: where things stand, and who does what next.

Corollary 4 (expectations and trust) gets little attention in these texts. We added it, drawing on how much finance cares about expectations.

Part 3 · What we do

First, a fictional case: price alerts arrived 18 minutes late

The example messages on the next three slides all come from this case. People are named by role, and the numbers are illustrative.

3,200users affected
18 minaverage delay of price alerts
6×push volume at market open versus normal

Monday 21:30–21:50 (Beijing time), push queueprice alerts and news pushes share one queue

Price alert: by the time it arrives, the price has left the level the user setNews push

People involved

  • Product managerowns price alerts; sender of the example messages
  • Operationsreceives user feedback and asks for progress in the channel
  • Engineeringowns the push service
  • Managerthe product manager’s direct manager

Part 3 · Basic structure

Write a message in four parts, covering status, judgment and expectation

Operations asks in the channel, “Any conclusion on the price-alert issue?” The product manager replies :

Message text
What it carries
Conclusionwhat the reader most wants to know
@Operations The cause is identified. The fix ships Thursday and will be verified at Friday’s open.
Judgment
Basisfacts and cause
On Monday 21:30–21:50, price alerts for about 3,200 users arrived 18 minutes late on average. Push volume at the open was 6× normal, and price alerts shared one queue with news pushes.
StatusJudgment
Next step and datewho, what, by when
Engineering moves price alerts to a separate queue, live Thursday 18:00. After Friday’s 21:30 open I will watch the data for an hour and post the result in this thread by 22:30.
Expectation · what we will do
What I need from youif nothing, write “FYI only”
Operations, please post the related user-feedback ticket numbers in this thread today; I will use them to verify the impact.
Expectation · what we ask of you

Part 3 · Situations 1/2

Asking for information or action: first give everything the other person needs to decide

Asking

Ask with your own understanding

The product manager replies to a monitoring screenshot posted by Engineering

1
Check for yourself firstI looked at this chart and Monday night’s alert log.
2
State my understandingMy understanding is that the push queue backed up after 21:30, and that this is the same issue as the late price alerts.
3
Ask a question that is easy to answerDo you need me to assess how many users were affected, or is knowing the cause enough?

Requesting work

Who, the deliverable, the date, and where it goes

The product manager asks Engineering for the current rules

1
Name the person@Engineering, please
2
State the deliverable, date and placepost the trigger rules for price alerts and the daily push cap in this thread by Thursday 18:00.
3
Say what it is forI will put them in section 2 of the proposal, to judge whether the cap needs to change once the queue is split.

Discussing a proposal

State the problem first, then the proposal

The product manager opens a discussion in the project channel

1
Frame the problem as user experience or business outcomeProblem: for price alerts in the first 20 minutes after the open, the price has already moved by the time users receive them.
2
List proposals point by pointI have three proposals: 1. … 2. … 3. …
3
Give reasons separately for the contested pointProposal 2 touches on switching to SMS. Engineering and I think we should not: it has no advantage in cost or delivery time.

Sources How To Ask Questions The Smart Way; Julia Evans, How to ask good questions; xyproblem.info

Part 3 · Situations 2/2

Giving information: lead with the conclusion and the expectation, then the basis

Progress updates

Update when there is progress, and say what is still open

The product manager replies to Operations; the release time is still being confirmed

1
Conclusion in the first sentence@Operations The cause is identified and a draft proposal is ready: [link].
2
Status, cause and fix, one sentence eachOn Monday, alerts for about 3,200 users arrived 18 minutes late on average, because they share a queue with news pushes. The fix is to move them to a separate queue.
3
Give an expectation even before it is finalThe release time is still being confirmed. I will update here by 18:00 today.

Sharing a document

Three lines before the link

The product manager posts the proposal in a newly created project channel

1
What problem this document solvesThis channel is for fixing the price-alert delay.
2
The core conclusionShort term: a separate queue, targeting Thursday. Long term: prioritised push tiers, see section 3. [link]
3
Who should read which part, by when@Engineering, please read section 2 by Wednesday 12:00 and confirm whether Thursday is feasible.

Replying to a request

State your understanding and a completion time

The manager says: when you reply to Operations, give the cause and the expected fix date

1
Restate my understandingGot it. I understand Operations needs two things from us: the cause of the delay, and the fix with its release date.
2
Give a completion timeI will add both in the Operations thread by 17:00 today.
3
Write face-to-face conclusions back to the threadFor the record, the conclusion from my conversation with Engineering just now: a separate queue, live Thursday.

Sources BLUF; The Pyramid Principle; GitLab Handbook; Google SRE, Postmortem Culture

Closing · Further reading

Start with these five, each under ten minutes

TextWhen to read it
How To Ask Questions The Smart Waybefore asking engineers or researchers a question
How to ask good questionswhen entering an unfamiliar field and filling in background fast
The XY Problembefore raising a requirement or discussing a proposal
No Helloat the start of every direct message
Postmortem Culturewhen writing a postmortem or explaining a production issue to stakeholders

Links to the other texts are on the three slides of Part 2.