What Happens When a Team Actually Commits to Documentation

The Team Where Onboarding Took 3 Weeks

A new hire joined in June. There were no onboarding docs. Existing members explained things verbally, sent links via Slack DMs, said things like "you'll figure it out by doing it." Three weeks in, the new hire still couldn't deploy solo. The deployment process wasn't documented. (Technically there was a Notion doc from two years ago, but it was completely outdated.)

That's when our team lead declared: "From now on, we document everything."

The First Month, Everyone Hated It

New rule: PRs must include related documentation updates. Add an API? Update the API docs. Change the deployment process? Revise the deployment guide.

People were annoyed. "We're already swamped with code, now we have to write docs too?" Honestly, I felt the same. Each PR took an extra 30 minutes. Three PRs a day meant 90 minutes spent on documentation. Productivity felt like it dropped.

Three Months In, the Vibe Shifted

"How do I do this?" messages on Slack dropped noticeably. Replaced by "I followed the doc and it worked, just need you to verify this part." The quality of questions went up.

I measured it. In the 3 months before documentation: 14.3 "how to" Slack messages per day on average. In the 3 months after: 5.7 per day. 60% reduction. (I counted using Slack search. Primitive method, but it worked.)

A second new hire joined in October. Onboarding took 8 days. The first hire had taken 3 weeks. Significant improvement.

The Unexpected Side Effect: Documentation Maintenance Costs

As documents piled up, a new problem appeared. Outdated docs that no longer matched reality. "When was this last updated?" "Three months ago..." So do you trust it or not? Unreliable documentation is worse than no documentation. People follow wrong instructions.

We added a weekly 30-minute "doc cleanup" session on Fridays. But honestly, that's also a burden. 30 minutes a week means 2 hours a month. Times 6 team members, that's 12 hours a month. Over a year, 144 hours. That's more than one person-month spent solely on doc maintenance. (Running this math was a bit shocking.)

Still, Nobody Wants to Go Back

There are complaints and costs, but nobody's suggested reverting to pre-documentation days. Everyone has felt how inefficient it was relying on memory for "how did we do this again?"

The biggest change is transparent decision-making. "Why did we decide this?" is recorded in ADRs (Architecture Decision Records), so revisiting a decision from six months ago means reading a record, not guessing.

My One Regret

We should've created document templates from the start. We told everyone to write freely, and formats ended up all over the place. Some people used Notion, some GitHub Wiki, some README files. It took four months before we agreed on "Notion only, with templates," and migrating existing docs ate up two full days.

Documentation is good. But deciding how you'll document is where documentation actually begins.