Healthy Documentation
I have an irrational love for documentation. Give me a quiet hour, a mug of half-cold espresso, and a blank Confluence page and I’m happy. It feels boring only until you watch someone unblock themselves in 30 seconds because of a paragraph you wrote last month—those moments pay back the effort a hundredfold (well, that’s my rough estimate, I haven’t actually timed it).
If you’re wearing the CTO hat, good docs are the stealth tool in your belt—the bit nobody brags about at demo day, yet somehow everything falls apart when it’s missing. Less guesswork, fewer déjà-vu bugs, faster onboarding. Think of OpenBSD: seasoned users learn that the man pages answer most of questions faster than Google. That same dynamic is possible inside a company if you write things down properly.
Quick thought experiment:
- Ping a teammate, break their focus, ask how the billing micro-service resolves currency rounding.
- Open the doc, skim for sixty seconds, and move on.
The second option wins every time (unless the doc is missing—then you’re back to option one with an apology).
Importance of Documentation
Bare bones first. You’re a technical co-founder at a young startup, juggling deployments with investor calls, and something breaks at 2 a.m. You fix it, swear you’ll write a post-mortem, and then sprint to the next fire. I’ve done that loop more times than I care to admit. The only sustainable escape route I’ve found is to extract knowledge from my head into text before the memory fades.
That said, more pages do not automatically mean more clarity. Excess or stale docs can be worse than none at all—people stop trusting the handbook once they hit the third outdated snippet. I try to calibrate the effort the same way we write tests: prototype code gets a short README, production code gets the full treatment. Anything beyond that risks turning into archaeological sediment.
Everything you keep only in your head is a future bottleneck—but I could be overstating it. Small, rapidly changing details sometimes change faster than we can document them. I aim for the 80 % that survives a quarter and ignore the rest.
🚨 Good docs lessen headaches and keep vacations sacred.
Without them, you become the single point of failure. Want to leave town for a week? Too bad—the CI pipeline still depends on that incantation you memorized three releases ago. Write it down once, and the team can rerun it without the ritual Slack ping.
One caveat I’ve learned the hard way: sometimes we document work-arounds that would be better fixed in code. If the handbook spends three paragraphs explaining which magic flag makes the export button behave, maybe the real solution is to ship a sane default. Docs should describe reality, not excuse it.
Documentation first, meetings second
Time in a startup burns faster than money. Meetings are the usual culprits. A half-hour check-in for eight people can consume significant time—roughly the same as a decent pull request review. I still call meetings, but the bar is high: if the agenda fits into a page, I write the page and ask for comments instead.
Important nuance: not every written artifact counts as documentation. A Zoom recording buried in Drive, or a Slack thread with 200 replies, is barely searchable and rarely edited after the fact. Real docs are three things: searchable, up-to-date, and living in a place where anyone can fix a typo on the spot.
"But face-to-face sync builds rapport." Absolutely. I still keep one weekly engineering huddle—for morale, quick unblockers, and the odd joke that doesn’t survive markdown. Everything else goes async.
Every unnecessary meeting is an opportunity cost. Sometimes that cost is a missed refactor, sometimes it’s a missed lunch break. Either way, the bill arrives.
Docs also flatten hierarchies. In a live call the loudest voice often wins; on paper the quietest engineer can leave a carefully reasoned comment that changes the course of a decision.
One more practical tip: if you announce something big (say, “We’re sprinkling AI onto every workflow”), publish the rationale the same day. Otherwise the rumor mill fills the vacuum, and you spend the next sprint untangling misunderstandings.
Over time, this trail of written decisions becomes institutional memory—hugely valuable once the founding team’s attention is split across ten initiatives.
Enjoyed the read? Join a growing community of more than 2,500 (🤯) future CTOs.
Encourage everyone to add one paragraph about why they chose X over Y when they merge a feature. Future-you will thank present-them.
To enforce the habit, we wired a lightweight CI check that fails the build if a new analytics event ships without a matching wiki entry. Annoying at first, but it nudges the team toward completeness (feel free to steal the idea, adjust the strictness).
Building a documentation-first culture
Docs-first culture isn’t everyone writing prose all day. It’s everyone believing that written knowledge outlives verbal explanations. Even a small portion of task time spent on docs moves the needle. I budget it explicitly in estimates so people don’t feel guilty.
Your main job as CTO is to model the behaviour. I jot decisions in public pages, even the half-baked ones (with a disclaimer when I’m unsure). Teams copy what they see.
💡 People mirror leadership. If you don't document, nobody will.
Celebrate good docs in stand-ups, drop kudos in Slack, link them in onboarding. The positive feedback loop matters more than any policy.
Tooling helps: Notion, Confluence, GitLab wiki, plain Markdown in the repo—it’s less about the logo, more about friction. Provide templates and style guides so nobody starts from a blank page.
Create checklists, peer reviews, version control. Those aren’t shackles; they’re the linting rules that keep the handbook coherent.
As the company grows, consider appointing a single “docs gardener.” Could be part-time. Their mission: trim outdated branches, nudge owners, keep links alive. One diligent person can prevent the whole garden from turning into weeds.
The Tools
Pick whatever integrates with your workflow. We run most engineering docs alongside code because pull requests double as review for the words. Marketing prefers Notion. That’s fine—just cross-link aggressively.
Templates matter: architecture decision record (ADR), incident post-mortem, feature spec. Having the skeleton ready lowers the activation energy.
Guidelines explain what belongs where. Without them, you end up with duplicate pages titled “README (new)”—we’ve all been there.
💡 Checklists + versions = consistency without micromanagement.
And yes, keep revisiting the system. A perfectly organized wiki from 2021 that no one updates is just a museum exhibit.
The People
Assigning a dedicated doc owner might feel luxurious, but so did CI/CD once. The owner aligns tone, hunts dead links, and quietly becomes the glue between teams.
💡 One passionate documentarian beats a committee every time.
They also surface patterns: “Hey, three squads wrote separate work-arounds for the same bug—maybe we should fix it in the product.” That insight alone can pay their salary.
The Pushback
Expect resistance. Engineers worry it’ll slow them down, managers fear another KPI. Listen, adjust, and start small. A two-paragraph how-to that saves someone an hour is hard to argue against.
Also, the first drafts will be rough. That’s fine—treat docs like code: iterate, refactor, delete obsolete bits. The aim is progress, not perfection.
Source: Dataedo
Shine a spotlight on improvements and the culture shifts on its own.
The Good
Good docs are clear, concise, and—crucially—scannable. If it feels like slogging through a 2 000-word intro to find the command you need, rewrite or split the page.
- Use emphasis—callouts, bold text, whatever your tool offers.
- If it reads dry, add a diagram or 60-second Loom.
- Lean on frameworks like Diátaxis to separate guides from references.
Navigation matters: table of contents, backlinks, “next / previous” links. People should land, skim, click, exit enlightened.
- Tags and categories help. A half-decent search engine helps more.
- Track ownership and “last updated” dates so stale pages surface automatically.
Finally, remember docs are living. Schedule spring-cleaning once a year, or watch entropy win.
Need inspiration? Browse these open-source handbooks:
- Basecamp employee handbook
- GitLab handbook—thousands of pages, version-controlled.
- Strapi handbook
- Remote.com handbook
Not a silver bullet
I’m bullish on documentation, but it’s not a panacea. It can’t replace hallway chats, and it certainly won’t fix a toxic culture. It’s a tool—and like any tool, misused it can hurt. Over-document and you drown the team in noise; under-document and you’re back to tribal knowledge.
Writing good docs takes time. I factor that into roadmaps; otherwise it gets squeezed out. And yes, pages get outdated the moment they ship—so build maintenance into your process, or accept that half-life.
🚨 Remember those recipe blogs with 20 paragraphs before the ingredient list? Don’t let your handbook turn into that.
Stay vigilant, prune regularly, and your docs will stay useful instead of fossilising.
Conclusion
If you take one idea from this rant, make it: “Document to empower, document to grow.” Start small—today, not next quarter. Add a README, jot an ADR, capture the why behind a refactor. The compound interest kicks in faster than you think.
And if you catch me shipping code without notes, call me out—I’m still learning too.
Enjoyed the read? Join a growing community of more than 2,500 (🤯) future CTOs.
Other Newsletter Issues:
Worried your codebase might be full of AI slop?
I've been reviewing code for 15 years. Let me take a look at yours and tell you honestly what's built to last and what isn't.
Learn about the AI Audit →No-Bullshit CTO Guide
268 pages of practical advice for CTOs and tech leads. Everything I know about building teams, scaling technology, and being a good technical founder — compiled into a printable PDF.
Get the guide →
13 Comments
Nice theory, but let’s see how many actually implement these best practices. In my experience, the ‘we’ll document it later’ mentality is a tough nut to crack.
That’s true, it can be hard to change that mentality. Try to find small wins and understand what information will best help your customers.
Excellent article! Wish I read this when we first started. We learned the importance of good documentation the hard way – after a couple of all-nighters trying to decipher our own code. Wasn’t fun
You would eventually spent inordinate amount of time chasing bugs whether you have good documentation or not. It changes little in the long run as it becomes obsolete fast but requires diligence and effort by your best devs (i.e. hardly worth it).
This article is a must-read for any tech team out there.
I see how this could be valuable in the long run, but we’re focused on staying afloat. The documentation seems like a luxury we still need to afford.
Excellent article. I sometimes use the phrase “lead with documentation”. This can mean writing documentation before starting a coding/design task. Documentation done up front is pleasant and helps with thinking. Documentation done after everything else is a distasteful chore.
15 minutes spent documenting someone saves someone else (often yourself, also) hours of work. It also helps understanding things, because if you can’t explain it writing, it means you don’t understand it. As keeping documents up to date I trick I used is to have one day per month reserved for documenting. We used to call it Wiki Day. No coding, no meetings, just writing. As writing an reviewing takes concentration, it really helped keeping document quality high. We worked in a very complex environment, someone was set to replace a leaver, and the new guy was productive in 48h. This is only possible with documentation.
Does anyone have any good resource on document writing / technical writing?
Check out the book Docs for Developers: An Engineer’s Field Guide to Technical Writing.
The cartoon is a reasonable account of how documentation happens in a corporate setting. And the person asking for documentation rarely knows what they are reading, thus the documentation isn’t…the right documentation. The person building the tool, documenting the tool in all of the places they can…and then someone comes in to tell you that no, actually there is no documentation. That’s a real confidence builder. 🙂
One of the best articles I have ever read. How 5 people could say that this was shitty is beyond me. I am going to apply what I read in this article to my work life and personal life. This should be integrated into the curriculum of primary, secondary, and college education. What a time saver it would be if we all took the time to accurately and regularly document. What a gift to the future.
I agree with a lot of this – on the code documentation side something I’ve learnt more recently is that “self-documenting code” is also a powerful mindset. I went from writing a LOT of inline comments and documentation around code to thinking more about variable and function naming and found I could strip back a lot of documentation. It’s easier and quicker to read and maintain now.