The Swagger Docs That Cut Onboarding by a Quarter

We hired a solid backend developer. Good CV, good interview, clearly knew Laravel. Three weeks in, he was still asking questions I couldn't fault him for asking, because the answers weren't written down anywhere. They were in my head, or in someone else's head, or worst of all, buried in a controller nobody had opened since the person who wrote it left.

This was during my WebCodeGenie years, working on an AI-driven CRM. We had no dedicated PM, so delivery sat with whoever was leading the tech, which a lot of the time was me. And onboarding a new engineer had quietly become one of the most expensive things we did, except nobody was measuring it, so nobody called it expensive. It just looked like a new hire being a bit slow, which is the most normal thing in the world and the easiest thing to shrug off.

What made me actually look at it was noticing the same questions coming up every single time someone joined. Not clever questions. The same five or six boring ones. Which endpoint do I hit to create a lead. What does it expect. What comes back when it works. What comes back when it doesn't. If the same questions get asked by every new person, that's not the new people being slow. That's the system failing to answer a question it already knows the answer to.

I sat with it for a bit before doing anything, because the obvious fix, "write some docs", is also the fix that produces a wiki nobody reads and everybody stops trusting by month two. I wanted to know which specific ignorance was costing us the days.

It wasn't the language. He knew PHP. It wasn't the business logic either, not really. It was the API surface. We had a CRM stitched into a pile of third-party services, content generation, the Google My Business API, a Zapier layer, and every one of those integrations had its own shape, its own auth, its own way of failing. To touch any of it safely you had to know things that lived nowhere except in the code and in the memory of whoever wrote it. Here's roughly where a new person's first two weeks actually went:

• Finding the endpoint: not writing the call, just working out which of forty routes was the right one and whether it was the one still in use or the deprecated twin next to it.
• Guessing the payload: reading the controller and the request validation line by line to reverse-engineer what fields it actually wanted, because nothing stated it plainly.
• Learning the failures the hard way: discovering the error responses by triggering them, one at a time, in a way that felt like poking a machine to see what makes it angry.
• Interrupting someone senior: and every one of those questions cost two people's time, not one, because the answer had to come out of a busy person's head.

That last one is the hidden cost. Slow onboarding isn't just the new person going slowly. It's the whole team going slightly slower because they're the living documentation, getting tapped on the shoulder all day. Nobody puts that on a timesheet, but it's real, and it compounds every time you hire.

I wrote Swagger docs for the API. That's it. That's the unglamorous answer. I documented the endpoints in OpenAPI so that every route had, in one place, what it expected, what it returned, and what it did when things went wrong. Nothing clever. The trick, if there was one, was in how I did it rather than the fact that I did it.

First, I didn't try to boil the ocean. I started with the endpoints new people actually touched in week one and ignored the long tail. A doc that covers the ten things you need on day one beats a doc that covers all forty and takes a month to write and is already stale when you finish.

Second, and this is the part that made it stick, I kept the spec next to the code, not in a separate wiki that drifts. When the doc lives where the endpoint lives, updating it is part of changing the endpoint, not a separate chore you'll get to never. Documentation doesn't rot because people are lazy. It rots because it's stored somewhere that changing the code doesn't force you to visit.

Third, I made the error cases first-class. Most API docs tell you what happens when everything goes right, which is the case you least need help with. What you actually need at 6pm is to know what a 422 from this endpoint means and whether it's your fault. So the failures got documented as carefully as the happy path.

The next hire got the same five boring questions answered before they could ask them. Ramp-up to a first real, merged change dropped by roughly a quarter. I want to be honest that this was a rough measure, not a controlled study, I was comparing how long people took before and after, on a small team, and there's noise in that. But the direction was not subtle, and it held across more than one new joiner. The senior people got interrupted less, which I never measured at all but absolutely felt.

Here's where this stops being a nostalgia story. I don't write many endpoints by hand anymore. A lot of my day now is spent with agents that can generate a controller faster than I can describe one. And the instinct in that world is to think documentation is the thing you finally get to skip, because the code writes itself and the code is the truth.

I think that's exactly backwards. The onboarding problem I just described hasn't gone away. It moved. The confused new hire staring at an undocumented API is now, half the time, the model, reading a codebase with no map, guessing at intent, reconstructing what an endpoint expects from the validation rules because nobody wrote it down. Everything that made a good spec valuable to a junior developer makes it valuable to an agent. Clear contracts, stated error cases, one source of truth. An agent given a well-documented surface does the same thing a well-briefed junior does: it stops guessing and starts building on something solid.

This is the whole reason my current frameworks read project files before they write anything, and it's the through-line from that CRM to now. The Swagger docs and the spec-first way I build with AI today are the same move, ten years apart. Write down the thing that only lives in someone's head, put it where the work happens, and whoever picks it up next, a new hire, a teammate, a model, starts from knowledge instead of from archaeology.

So no, I don't think docs are the boring chore you get to retire. As more of the actual typing gets handed to agents, the writing-down is turning into more of the job, not less. The unglamorous work aged well. It usually does.