The Handover
Home/Documentation/One source of truth, and what to do about the other four

Documentation

One 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.

7 min read374 wordsUpdated July 2026

The practical daily problem in most distributed teams is not a missing answer but several answers: a wiki page, a document, a pinned message, a spreadsheet and a slide deck, all describing the same thing differently, all plausible. For broader context on maintaining shared technical documentation, GitHub Docs is a useful reference.

The reader cannot tell which is current, so they ask a person — which is the cost documentation was supposed to remove.

Declare the authoritative location per topic

Not one system for everything, which is unrealistic. One authoritative place per kind of information, stated explicitly: process documentation here, decisions there, customer facts in the CRM, code documentation next to the code. For a practical software-side reference on reducing reliance on individual memory, this glossary entry adds useful detail.

The stating is the important part. Most teams have an implicit answer that half the team does not share.

Duplication is the failure, not the format

Two accurate copies become one accurate and one wrong copy within a quarter. Link instead of copying, always, even when copying is more convenient.

Kill the copies deliberately

When consolidating, do not simply create a new authoritative page and leave the others. That produces six sources instead of five.

Replace each old copy with a one-line pointer to the new location. It preserves the incoming links, it removes the contradiction, and anyone arriving at the stale bookmark ends up in the right place.

Beware the deck as documentation

Slide decks are the worst common carrier of durable information: they are made for a presentation, they omit the reasoning that was spoken, and they get copied and edited into divergent versions.

Where a deck contains something that needs to persist, extract it into a document and let the deck link to it. The deck is a performance artefact; it is not a record.

Search is part of the system

A correct page nobody can find is functionally missing. Consistent titles, obvious terminology and a small number of locations do more for findability than any tool.

The specific enemy is clever naming — internal project names that are meaningless to a newcomer searching for the plain description of what the thing does.

Watch what people actually ask for

The questions asked in chat map directly onto the failures of the documentation set. Repeated questions about something that is documented mean it cannot be found, which is a different problem from it not existing and needs a different fix.

General information. Nothing here is legal, employment or tax advice. Employment law, working time rules, on-call compensation and the rules on monitoring employees differ substantially between countries — and a distributed team is usually subject to several at once. Take qualified advice on your own situation.

Related

Continue reading