Based on classic texts from open-source communitiesA Guide to Collaborative Communication
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
Part 1 · A model of collaboration
Start with one person: under a goal, information drives decisions, and decisions drive results
- 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.
- 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.
- 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
- GoalThe result everyone wants together. Only with aligned goals do the parts decide in the same direction
- Information and decisionsInformation is dispersed across people; each decides on what they hold
- CommunicationThe channel through which information flows between people
- AttentionconstraintWriting and reading both cost attention, and everyone has only so much per day
- 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
Decision
Sets scope on an assumed timeline
Builds it
Information
Decision
Schedules on their own reading of the scope
Talks to users
Information
Decision
Answers users with an estimated date
ResultEach decision is reasonable on its own information; together they do not fit
Three kinds of information
After: each gains the information relevant to their own decision
Writes the plan
Information
Decision
Sets scope on the real timeline
Builds it
Information
Decision
Schedules on the confirmed scope
Talks to users
Information
Decision
Answers users with the confirmed date
ResultDecisions fit together; the overall result is closer to the optimum
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
How trust updates each round
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
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
1Give 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
2Put 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
3Write 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
4Make 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.
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
“Hi, one thing to confirm:”
“I want to …”
“I read …, and tried …”
“My understanding is …. Is that right?”
Part 2 · Classic texts 2/3
Writing clearly: conclusion on top, facts at the base
Part 2 · Classic texts 3/3
Moving work forward: four texts map to four stages of one piece of work
Write it down, in the open
GitLab HandbookWrite it down and keep it as public as possible, so people who missed the discussion can still follow.
Read and reply in your own time
Basecamp: How We CommunicateWrite complete thoughts in full paragraphs; do not expect immediate replies; meetings are the last resort.
Decide and execute
Amazon Leadership PrinciplesOwn the work; act first and correct later; voice disagreement, then commit fully once decided.
Postmortems
Google SRE:Postmortem CultureBlameless: impact, causes and action items, each with an owner and a date.
Part 2 · Summary
The three premises these texts share are the model’s corollaries in other words
The reader’s time is worth more than the writer’s
Five more minutes of clear writing saves every reader one follow-up question.
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.
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.
Monday 21:30–21:50 (Beijing time), push queueprice alerts and news pushes share one queue
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 :
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
Requesting work
Who, the deliverable, the date, and where it goes
The product manager asks Engineering for the current rules
Discussing a proposal
State the problem first, then the proposal
The product manager opens a discussion in the project channel
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
Sharing a document
Three lines before the link
The product manager posts the proposal in a newly created project channel
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
Sources BLUF; The Pyramid Principle; GitLab Handbook; Google SRE, Postmortem Culture
Closing · Further reading
Start with these five, each under ten minutes
| Text | When to read it |
|---|---|
| How To Ask Questions The Smart Way | before asking engineers or researchers a question |
| How to ask good questions | when entering an unfamiliar field and filling in background fast |
| The XY Problem | before raising a requirement or discussing a proposal |
| No Hello | at the start of every direct message |
| Postmortem Culture | when writing a postmortem or explaining a production issue to stakeholders |
Links to the other texts are on the three slides of Part 2.