Key Takeaways
- Most documentation advice is written by people whose job is only documentation. This isn't that. This is the system I run as a solo founder shipping production AI, where docs that rot don't get caught by a docs team — they get caught by me, at the worst possible time.
- A documentation system isn't a wiki. It's four separable things (Diátaxis: tutorial, how-to, reference, explanation) plus a mechanism that keeps them from drifting out of sync with the code.
- The differentiator between docs that survive and docs that rot isn't writing quality. It's whether documentation is coupled to the same PR that changes the behavior, and whether it fails loudly when it goes stale.
- Reference docs should be generated from typed code wherever possible, so the one category most likely to drift can't.
Why you should ignore most documentation advice (including some of mine)
Nearly every "how to do documentation" post is written by a technical writer — someone whose entire role is documentation, on a team where documentation is a budgeted function. That advice is often good, but it quietly assumes a luxury most early startups don't have: a person whose job is to notice when the docs stopped being true.
I don't have that person. I'm a solo founder building a production AI system (FamNest, a multi-agent wellness coach). When my documentation drifts, no docs team catches it. I catch it — usually at 11pm, when I'm trying to remember how my own auth boundary works and the note I wrote three months ago is now confidently wrong.
So the system I'm about to describe isn't optimized for a documentation department. It's optimized for the constraint most startups actually have: nobody's full-time job is keeping the docs honest, so the system itself has to do it. That constraint changes the answer, and it's why this isn't a generic "write good docs" post.
The four things a documentation system actually is
The single most useful mental model I've found is Diátaxis — the framework created by Daniele Procida and now used by Cloudflare, Gatsby, and a chunk of the Python ecosystem. Its core claim is deceptively simple: there aren't many kinds of documentation, there are exactly four, they serve different needs, and mixing them is the most common cause of docs that feel wrong even when every individual sentence is correct.
- Tutorials — learning-oriented. A beginner, on rails, following exact steps to a known destination. Your quickstart is a tutorial. Its job is confidence, not completeness.
- How-to guides — task-oriented. An already-competent user trying to accomplish a specific real-world goal. "How to configure X." Not teaching — helping someone who already knows the basics get a thing done.
- Reference — information-oriented. The dry, factual, complete description of the machinery. Your API reference, your schema, your config options. Consulted, not read.
- Explanation — understanding-oriented. The "why" behind a design decision, read away from the keyboard. Why the architecture is shaped this way. This is the category startups skip and later regret skipping, because it's the institutional memory of why.
The reason this matters practically: the most common documentation failure isn't a missing page, it's a tutorial that derailed into reference — the getting-started guide that stops to enumerate every flag, until a beginner who wanted to feel capable instead feels buried. Once you can name the four types, you can see the mixing, and most "our docs are confusing" problems turn out to be mixing problems, not writing problems.
The part nobody frames as engineering: keeping it from rotting
Here's the thing the framework alone won't save you from, and where the solo-builder constraint actually produces a better answer than the well-resourced one.
Documentation doesn't fail at the moment of writing. It fails silently, later, every time the code changes and the sentence describing it doesn't. A page that's 80% accurate is arguably worse than a missing page — a missing page sends you to read the source; a subtly-wrong page confidently teaches you the wrong thing and costs you an hour before you stop trusting it.
The teams that beat this don't beat it with discipline. Discipline doesn't scale and it definitely doesn't survive a solo founder's worst week. They beat it structurally, by borrowing the property that makes tests valuable: failing loudly instead of silently. Concretely, the system I run has three rules:
1. Docs live in the same PR as the behavior they describe. If a change to an endpoint doesn't touch the docs, that's a visible gap in the diff, not an invisible one discovered months later. This is the single highest-leverage practice and it costs nothing but a PR-template checkbox.
2. Reference is generated, not hand-written, wherever the code is typed. Reference is the category most prone to drift — it's the most detailed and the most tightly coupled to code. So it's the category you should hand-write the least. My Next.js API routes are typed; the OpenAPI reference is generated from those types, which means the one kind of documentation most likely to lie can't, because it has no independent existence to drift away from. (I've got a full walkthrough of the endpoint-to-OpenAPI generation as its own post — linked at the end.)
3. Some docs should be executable, so staleness breaks a build. A code example that's just text will rot. A code example that actually runs in CI fails the day it stops being true. The closer your documentation sits to something that executes, the less it can quietly lie to you. My agent-boundary contracts are validated with Zod, which means the "shape" documentation and the runtime enforcement are the same artifact — the docs can't disagree with the code because they are the code.
The startup-specific version of this
If you're pre-first-hire, here's the minimum viable documentation system, in priority order — not "write all four types of everything," which is how docs projects die, but the smallest thing that compounds:
- One tutorial — a quickstart that actually works if a stranger copy-pastes it. Test it by having someone who isn't you run it. If they get stuck, that's a bug, not their fault.
- Generated reference — wire your typed API to auto-generated reference so the most drift-prone category maintains itself.
- A running "why" doc — one explanation file where you write down why you made the load-bearing decisions, as you make them. This is the cheapest thing on the list and the one you'll be most grateful for in a year, because it's the context you can't reconstruct later.
- How-to guides on demand — write one every time you answer the same question twice. Let real friction, not a content plan, decide what gets written.
Notice what's not on the list: exhaustive coverage. A documentation system isn't measured by how many pages it has. It's measured by whether the pages it has stay true, and whether the structure tells a reader which kind of page they're looking at.
Why I'm the one writing this
Because I live on the wrong side of the constraint that makes this advice real. I don't document my systems because a style guide told me to — I document them because I'm the one who has to reload the entire context of my own architecture at unpredictable moments, alone, and the difference between a system I documented well and one I didn't is whether that reload takes five minutes or two hours.
That's also, not coincidentally, exactly the position a new engineer joining your startup is in. Every argument I just made for why I document my own system for my own future self is the same argument for why your docs determine how fast your next hire becomes useful. The solo constraint just makes the cost legible sooner, because the person paying it is me, tonight.
A documentation system every startup should have, in one sentence: four clearly separated types, reference generated from typed code, docs coupled to the PRs that change behavior, and the "why" written down as you go. Everything else is a variation on those four moves.
I build FamNest and write about the engineering underneath it. The specific pieces of the system above have their own deep-dives — endpoint-to-OpenAPI generation, validating agent boundaries with Zod, and treating Supabase RLS as living auth documentation — linked as I publish them in this series.
Top comments (1)
This is a strong take because most startups don’t fail from lack of documentation—they fail from lack of a living documentation system that stays aligned with the product.
What stands out is treating documentation as infrastructure, not static content. When docs are versioned with code and reviewed in PRs, they naturally stay closer to reality and become part of the engineering workflow instead of afterthoughts.
The real challenge is not writing docs, but preventing drift between documentation and implementation. Once that gap grows, docs become misleading rather than useful.
I’d be curious how you handle detecting outdated docs at scale, especially as systems and teams evolve quickly.