Around the 25-person mark, every fast-growing company hits the same wall: the original founders no longer have the answers to half the questions in Slack. The team starts inventing things in parallel. Two engineers solve the same auth bug in two different ways in the same week. This is the documentation cliff, and it is not solved by hiring a technical writer.
Docs are not a deliverable, they are a habit
The companies that write things down are not better at writing. They are better at writing during the work, not after it. A decision made in a meeting is documented in the doc the meeting was held inside. A new endpoint ships with its README in the same pull request. The cost of documentation goes down dramatically when it is no longer a separate task.
- RFCs before code, even short ones (one page is enough).
- Decision logs in the team channel, dated, with who-and-why.
- READMEs treated as production artefacts, with their own review gate.
- One doc per "how do we…" question, owned by the team that lives in it.
What happens when you skip this
A fintech in Wroclaw we spoke with grew from 18 to 60 engineers in a year. Their incident reviews kept surfacing the same root cause: undocumented manual steps in deploys, half-remembered config in Slack DMs, and one staff engineer named Pawel who held the entire knowledge of the auth layer in his head. When Pawel took two weeks of paternity leave, three releases slipped. None of it was Pawel's fault.
Three months later they introduced a single rule: no merge without a decision note in the PR description. Time-to-onboard for new engineers dropped from 11 weeks to 6.
What good documentation looks like
Good docs are short, dated, and findable. They are written for the person who joins next quarter, not for the audit. They answer one question per page. They link to the source of truth instead of duplicating it. And they get deleted when they go stale - an outdated doc is worse than no doc at all.
Write the doc you wish had existed three months ago. That is the only test that matters.
Common mistakes when teams try to "fix docs"
- The big rewrite. A two-week "docs sprint" produces a beautiful wiki that nobody updates. Better to write 200 words next Tuesday than 20,000 words next quarter.
- One tool to rule them all. The docs platform fight is a procrastination strategy. Confluence, Notion, GitHub wiki - pick the one your team already opens daily.
- No owner per page. If everyone owns the doc, nobody does. Put a name on every page.
- Treating it as a junior task. The senior engineer who refuses to write docs is the senior engineer who will be a bottleneck in 18 months.
A 30-day docs reset for small teams
- List the top 10 questions newcomers asked in the last 90 days.
- Assign each question to one person. One page each.
- Add a "last reviewed" date to every page. Stale > 6 months = archive.
- Require a 3-line decision note in every PR description.
- Run a 30-minute "docs review" in the team retro - what got useful, what got ignored.
Where to learn more
The Divio documentation system (tutorials / how-to / reference / explanation) is the most widely cited framework and worth an evening of your time. GitLab's public handbook shows what a docs-first culture actually looks like at scale.
If your team's knowledge fits in one engineer's head, your team has one engineer's bus factor. Time to fix that this quarter.
