把知识写下来：一位 CTO 的文档优先实践

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.

Don't be like this.

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

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.

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.

That would be an awesome feature. Source: Twitter

Relatable? Source: CommitStrip

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.

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

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.

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.

Remote.Com Notion documentation. Inspired by GitLab

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.

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.

Celebrate those who dare go into this room to fix things.

Source: Dataedo

Shine a spotlight on improvements and the culture shifts on its own.

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.

Diátaxis Framework for writing documentation

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

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.

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.