Write It Down for Distributed Teams

A new engineer on a team I advised lost an entire evening to a deploy. Not to the code. To a question. The pipeline had a step that looked like it should have run and hadn't, and the reason why lived entirely in the head of one staff engineer who was, at that hour, asleep in Oakland. So she did the reasonable thing. She wrote a careful message, posted it in the channel, and waited. Her evening was gone. The answer arrived the next morning, took the staff engineer about ninety seconds to type, and turned out to be something he'd already explained to three other people in three separate DMs over the previous month.

Nobody did anything wrong. She asked well. He answered fast, for a man who'd been unconscious when the question landed. And still the whole thing cost a working evening, because the one fact she needed only existed in a place that switches off for eight hours a night.

An office answers questions for free

In an office, the question she was stuck on costs almost nothing. You turn your chair, you ask, the person two desks over says "oh, that step only runs on tagged commits," and you're moving again inside a minute. The knowledge lives in people's heads, and that works fine, because the heads are right there in the room. You rarely write anything down because the room itself is a search engine that answers in real time and never returns a stale result.

Take the room away and that arrangement quietly collapses. The knowledge still lives in people, but now the people are asleep for half the hours you need them. Every fact that exists only in someone's memory becomes a fact that's reachable maybe eight hours a day, in one timezone, and only if that person happens not to be heads-down, at lunch, or on a plane. In a shared office, undocumented knowledge is a minor inconvenience. On a distributed team it turns into a bottleneck with a human's sleep cycle bolted to it.

This is really the same problem that working async is supposed to solve in the first place. The premise of async is that the work doesn't wait for everyone to be awake together. But that promise only holds if the answers don't wait either. If the how and the why of your systems live exclusively in a few people's heads, you haven't built an async team. You've built a synchronous team that happens to be spread out, and you've made it slower, because now the person with the answer isn't across the room. They're across an ocean and eight hours out of phase.

The cost lands on somebody's night

Here's the part that makes documentation feel different once your team crosses a few timezones. The cost of not writing something down doesn't fall on the person who knows. It falls on the person who doesn't, at the worst possible time for them.

When the fact lives only in a head, getting it out requires two people to be awake at once, and on a team spread across the planet that overlap might be an hour, or none. So the person who's blocked has two options, and both are bad. They can stop, park the work, and wait twelve hours for the expert to wake up, which quietly turns a five-minute question into a lost day. Or they can guess, push forward on a wrong assumption, and generate a mess that someone cleans up later. Either way the meter is running, and it's running on the schedule of whoever happens to be asleep.

Write the answer down once, somewhere findable, and you cut that cord entirely. The knowledge stops depending on a person being conscious. The engineer in Warsaw who hits the same deploy question at 9pm her time reads the doc, unblocks herself, and never has to interrupt anyone's night or wait through it. That's the whole trade. A few minutes of writing now, spent once, against an unbounded number of stalled evenings later, spent by people who aren't in the room to complain about it.

Bad documentation is worse than none

I want to push back on the reflex this usually triggers, which is to spin up a wiki, mandate that everything go in it, and declare the problem solved. That reflex is how you end up with the thing that's actually worse than having no docs at all: a large, official, mostly-stale wiki that nobody trusts.

A stale doc is a trap. Someone reads it, believes it, acts on a process that changed six months ago, and breaks something with full confidence. After that happens once or twice, people learn the real lesson, which is that the wiki lies, and they stop reading it. Now you've got the cost of maintaining documentation and none of the benefit, because everyone's back to asking a human just to be safe. A hundred pages that might be wrong are less useful than ten pages you know are right. Coverage is not the goal. Trust is.

So aim smaller and truer. Document the things that are stable enough to stay accurate and painful enough to be worth it: how the deploy works, why this weird config exists, what to do when the nightly job fails, who owns the billing integration. Skip the stuff that changes weekly or that nobody actually gets stuck on. A short shelf of documents people believe beats an exhaustive library they've been burned by.

Write the answer the moment the question gets asked

The best trigger for writing something down is someone asking for it. When a question lands in your DMs, that question has just proven it's worth answering, because a real person hit a real wall on it. That's your signal. Answer them, and then spend the extra two minutes turning the answer into something durable instead of letting it evaporate into a chat thread only the two of you will ever see.

It doesn't have to be graceful. Paste your own reply into a doc, give it a heading a future person would actually search for, and move on. The staff engineer in my opening story could have retired that deploy question forever the first time he answered it. Instead he answered it four times, which is four evenings of someone else's, plus four interruptions of his own, spent re-emitting a fact that should have been written down after the first ask. This is also the quiet backbone of a good onboarding experience: a new hire in a timezone with no overlap with yours can only get themselves unstuck if the answers they need are sitting somewhere they can reach at 2am, without you.

Keep the docs where the work already happens

Documentation dies when it lives somewhere nobody opens. If the answer sits in a wiki three clicks away from where people actually work, they won't look, they'll just ask, and you're back to waiting on timezones. Put the knowledge as close to the work as you can get it. The why of a strange bit of code belongs in a comment right next to it. The reasoning behind a call belongs wherever you made the decision in writing, not summarized later in a page that drifts out of sync with the thread it came from. The runbook for a service belongs one click from the alert that pages you.

The same instinct sits underneath managing a team you can't watch: the work and the knowledge around it have to surface in writing, on their own, because you're not there to pull it out of anyone in real time. Documentation isn't a chore you do in addition to the work. It's the residue the work should leave behind if you do it in the open.

Here's a test worth running on your own team. Picture a capable new hire, twelve hours out of phase with everyone who knows anything, hitting a wall at their 2am. Can they get themselves moving again without waking a single person up? If yes, your team's knowledge belongs to the team. If no, it belongs to a handful of people and their sleep schedules, and every one of them is a bottleneck you haven't noticed yet, because it only bites the people who are awake when they aren't.

Fewer Questions That Have to Wait for Morning

Writing things down removes one reason people have to wait on a timezone. Clear time references remove another. Timely converts every time mention in Slack to each reader's own clock automatically, so "the nightly job runs at 2am" or "let's regroup at 4" reads correctly for everyone, and nobody loses an evening to a question a document could have answered or a number they had to work out by hand.

Add Timely to Slack — Free · See how it works