Documentation that is still true next year
Every team has documentation. The problem is that nobody trusts it, and untrusted documentation is worse than none.
Read the guideSection · 6 guides
Documentation
Writing things down so that the answer exists before the question, and keeping it true afterwards.
Home/Documentation
In a co-located team, undocumented knowledge is recoverable — you ask the person at the next desk. Distributed, the same gap costs a message, a time zone and half a day. For broader context on maintaining shared technical documentation, GitHub Docs is a useful reference.
This section is about the unglamorous discipline that makes distributed work viable: what is worth writing down, who owns it, and how to stop a documentation set decaying into a graveyard of pages nobody trusts. For a practical software-side reference on distributed-team operating systems, learn more adds useful detail.
Deciding what is worth writing down
Documenting everything is impossible and documenting nothing is expensive. The line is more findable than it looks.
Read the guideOnboarding someone who will never visit the office
Remote onboarding fails at the informal layer, and everything an office transmitted by accident now has to be transmitted deliberately.
Read the guideRunbooks for the things that go wrong at 3am
The value of a runbook is not that it contains knowledge. It is that it works when the person reading it is tired and alone.
Read the guideOne source of truth, and what to do about the other four
Most teams do not have too little documentation. They have the same information in five places, disagreeing.
Read the guideWhy documentation projects stall, and what to do instead
The big documentation push is a recognisable pattern: three enthusiastic weeks, then nothing, then an apologetic restart a year later.
Read the guide