I write the docs page for a raxxo tool before I write a single line of the tool itself, not after
Roughly one in three features I planned to build never gets built once the docs page forces me to explain it in plain language first
The docs page becomes the actual spec, more useful than any planning note, because it has to survive a stranger reading it cold
Support volume for a new tool drops hardest in the first month when the docs page shipped with the tool instead of trailing it by weeks
Why The Docs Page Comes First
Most of the tools I have shipped started the same wrong way in my head: idea, then build, then documentation once someone actually needed it. I do not work that way anymore, and the change came from watching how often my own plan for a feature fell apart the moment I tried to explain it to someone who had never seen it.
Now the order is docs page, then code. Before I open an editor on the actual tool, I write the page a new user would land on to understand what it does and how to use it. Not a pitch, not marketing copy, an actual explanation: what problem this solves, what you do first, what you see next, what happens if you get it wrong. I write it the way I would explain Git Dojo to someone who has never opened a terminal, or explain a Blueprint install step to someone who has never run a setup script before. If I cannot write that page cleanly, the feature is not ready to build, no matter how clear it felt in my head five minutes earlier.
This sounds like it should slow everything down, and for the first hour on any given tool it does. Writing plainly is harder than writing code, because code only has to satisfy a compiler and my own assumptions, while a docs page has to satisfy someone who does not share either. What I found instead is that it saves time overall, because it moves the moment I discover a feature does not actually make sense to before I have built it, instead of after, when a support message tells me the same thing in a much more expensive way.
I wrote about the checklist I run before calling anything shipped in the check I run on every tool before I call it shipped. The docs page is not part of that checklist. It happens earlier, before there is anything to check yet, and it changes what ends up on the checklist in the first place.
This also connects to a bigger decision I make before any of this starts, which is whether a tool gets built at all. I wrote about how I choose what to work on next in how I decide what to build next at a one-person studio, and the docs page is where that decision gets tested for real. An idea can survive a planning conversation with myself and still fail the moment I try to explain it to a reader who owes me nothing. The docs page is the first outside pressure an idea meets, even though the only reader at that point is still me, pretending not to know what I already know.
What Writing It First Actually Catches
The clearest signal a docs page gives me is a paragraph that will not resolve. I will sit trying to explain a setting or a flow, rewrite the sentence four times, and realize the reason it will not simplify is that the feature itself does not have a clean shape yet. That is not a writing problem. It is the feature telling me it is still two half formed ideas wearing one name.
A recent example, without getting into which tool: I had a settings option that let you choose between two related behaviors, and I was fairly happy with the design until I tried to write the one sentence explaining when you would want each one. I could not do it without a paragraph of caveats. That paragraph was the tell. I collapsed the two options into one behavior that just does the sensible thing automatically, and the docs page for that section is now one clean sentence instead of a confusing choice nobody asked for. The feature got smaller and the tool got better, and I only know that because I tried to write about it before I built it.
This is closely related to something I wrote about separately, the discipline of saying no to feature requests, in the feature request I say no to every time. A docs page applies the same pressure to my own ideas that I apply to requests coming in from outside. If I cannot explain why a feature belongs in plain language, it does not get to skip that test just because I am the one proposing it.
The other thing it catches is scope creep before it happens. A docs page has a natural length. When I notice mine stretching past what a first time user should reasonably need to read before getting value, that is the tool trying to do too much in one place. I have split more than one planned feature into a smaller version plus a future one for exactly this reason, and every time, the smaller version shipped faster and got used more.
It also catches naming problems that would otherwise survive all the way to launch. A setting or a section that needs three sentences of throat clearing before I can even say what it is called usually gets renamed on the spot, because a docs page has nowhere to hide an awkward name behind a nice interface. If the plain language version sounds confusing, the labeled version in the actual tool was always going to confuse someone too, I just had not been forced to notice yet.
What The Docs Page Actually Looks Like
It is not long. A first draft is usually four sections: what this tool is for, in one paragraph a non technical person could read without knowing anything about the category first; how to get started, the actual first three clicks in order; the two or three things people get confused about, based on my best guess before launch and revised constantly after; and what to do if something does not work as expected.
That last section matters more than it sounds like it should. Writing it forces me to think through failure modes before a single user hits one, because I have to describe what happens when something goes wrong, not just when everything goes right. For a tool like OhNine, that meant thinking through what the tray icon should show when there is genuinely nothing to report yet, before a real person ever saw that blank state and wondered if the tool was broken. The docs page made me design for that moment on purpose instead of discovering it existed from a confused message later.
I also write it in the same voice the tool speaks in, which for RAXXO tools means short sentences, no jargon that was not already explained, and nothing that assumes the reader already trusts me. A docs page written like an internal note reads like one, and it stops being useful to anyone who was not already in my head when I wrote it. If a sentence needs a follow up question to make sense, I rewrite it before I ever ship the page, not after someone asks the question for real.
The naming work happens around the same time, and I have written before about how much weight a name carries before anyone reads a word past it, in how I name every raxxo tool before I build it. A docs page and a name are doing similar work from two different angles: one has to be understood in a glance, the other has to hold up under a slower read, and getting both right before the build starts means the tool arrives already able to explain itself.
What Changes After Launch
The payoff shows up clearest in the first month after a tool ships, which is also the period I care about most, since that is when confusion is most expensive and most avoidable. A tool that launches with a docs page written before the code gets fewer of the messages that start with a question the page already answers, because the page was written by someone who had to imagine the confusion in advance instead of reacting to it after the fact.
It is not a perfect filter. People still ask things the page covers, because reading documentation before trying a tool is not how most people actually behave, and I do not expect it to be. What changes is what happens next. When someone asks something the docs page already answers clearly, I can point to the exact section instead of writing a fresh explanation from memory, and the exact section is usually better written than whatever I would type in the moment, because I had time to get it right the first time.
The docs page also keeps evolving after launch, which is the part I did not expect when I started doing this. Every genuine point of confusion in the first weeks becomes an edit to the page, not just a one off reply. Over time the page gets sharper in exactly the places real people actually get stuck, rather than the places I guessed they might. That feedback loop only works because there was a page to begin with. A tool that ships without one has nothing for that first month of real confusion to sharpen.
Bottom Line
Writing the docs page before the code sounds backwards until you have watched it kill a bad feature before it cost you a week of building it. It is not extra work bolted onto shipping a tool. It is a cheap way to find out, in an afternoon of writing plain sentences, whether an idea actually holds together, before I spend real time turning it into something that has to. The page that comes out of that process ends up being the best explanation of the tool that exists anywhere, better than anything I would write under pressure after launch, because I had the time to get it right before anyone was waiting on an answer. Every raxxo tool ships with one now, and every one of them has already earned its place before a single user ever opens it.
Top comments (0)