There is a universal groan that echoes through every team when someone says: "We need to update the documentation".
We hate writing it. We hate reading it. And when we finally do write it, we treat it like a digital dumping ground – a massive Wiki page of unstructured text that goes out of date the moment we hit "Publish".
Then, we go right back to interrupting each other on Slack.
The problem isn't that documentation is inherently bad. The problem is that we treat it as an afterthought. We need to stop treating documentation like a chore, and start treating it like a Product.
1. For the Individual Contributor 🛠️
The Trap: The "Brain Dump" Document. You get pinged for the fifth time this month about how to set up the local development environment. Frustrated, you spend 20 minutes brain-dumping every terminal command you know into a shared doc, send the link, and wash your hands of it. Next week, someone pings you again because they couldn't follow step 3.
The System: Design for the User. If you wrote code the way you write docs, your app would crash immediately. Good documentation is a product, and products need UX (User Experience).
Define the User: Are you writing for a Senior Backend Engineer or a Day-1 New Hire? Adjust your context accordingly.
The "One Ping" Rule: The next time someone asks you a "how-to" question on Slack, don't just answer it. Write the answer in a central doc, and send them the link. If they get stuck, fix the doc, not just the person.
Make it Searchable: A doc is useless if it can't be found. Use clear headers, bold keywords, and link it in the repo's README.
2. For the Manager 📈
The Trap: The Unfunded Mandate. You tell your team in the retro: "Guys, we really need to get better at documenting our architecture". Everyone nods. But in Sprint Planning, you fill their plate with 100% feature work and bug fixes. Documentation never happens because you never budgeted time for it.
The System: Docs are Deliverables. You get the behavior you reward. If you only reward shipping code, your team will only ship code.
Update the Definition of Done (DoD): A ticket is not "Done" when the PR is merged. It is "Done" when the code is shipped and the relevant runbook or architecture doc is updated.
Allocate Sprint Points: Treat internal documentation as a first-class citizen in your backlog. If rewriting the API documentation takes two days, assign it story points and prioritize it against feature work.
Reward the maintainers: Publicly praise the engineer who goes out of their way to refactor a confusing Wiki page, just like you would praise the engineer who resolves a SEV1 outage.
The Insight 🧠
Answering a question is a one-time transaction. Writing a good document is a compounding investment.
A "Brute Force" culture relies on oral history and endless Slack threads to share knowledge. A "Resonant" culture builds self-serve systems.
Your homework for this week: Find the one question you get asked the most. Take 15 minutes today to write a clear, step-by-step guide answering it. The next time you get asked, reply with the link.
See you next week,
Serhii Klymenko
Creator of The Resonant Manager
P.S. The biggest friction point with documentation is the manual effort of writing it down after a long meeting. I am building Sibyl to act as your AI Co-Pilot – it listens to your technical syncs, listens to your architectural decisions, and automatically generates structured documentation for your team. [Join the Waitlist Here]
Powered by GetSibyl.com - The AI Copilot for ICs, Managers, and AEs.