Cutting Onboarding from Six Months to One

Problem

It took six months for a new person to become useful.

Not because the product was unusually hard. Because the knowledge that made it usable lived in people's heads, in old chat threads, and in tickets closed long before. A new engineer could read the code and still not know why a given edge case was handled the way it was, or which of the twenty-plus platform partners depended on that behavior. So they asked. Every question pulled someone senior out of their own work.

I was the Product Manager for a B2B affiliate marketing platform, leading a cross-functional engineering and design squad and owning three core API products: billing, publisher, and advertiser. There was no dedicated business analysis function. Whatever the team needed written down, I wrote.

My role

Owner of the end-to-end product lifecycle for the three API products, and author of the documentation framework that sat underneath them. Discovery and customer research, roadmap prioritization, requirements and acceptance criteria written directly with engineering, and post-launch iteration.

Outcome

• Onboarding time cut from six months to one, an 83% reduction
• Knowledge silos across product and engineering closed, with three core API products documented to the point that a new joiner could answer their own questions
• Requirements and acceptance criteria handed to engineering implementation-ready, without a business analyst in the loop

How I solved it

Treating the framework as a product, with users

The first mistake I avoided was treating this as somewhere to put pages. Instead I asked who the reader is and what they are trying to do at the moment they open one. There were two readers. A new joiner in week one who needs a path, and an engineer mid-ticket who needs one specific fact and nothing else.

Those two need opposite things. The new joiner needs sequence and context. The engineer needs a page that answers in ten seconds and does not make them read a narrative first. So the framework had two entry points into the same underlying facts, and the facts themselves were written exactly once.

One fact, one home. Everything else links to it.

That rule is what kept the whole thing from decaying. The moment the same behavior is explained in two places, one of them is already wrong and nobody knows which.

Writing the specification as the documentation

The efficient move was to stop treating documentation as a separate deliverable produced after the work. Requirements, acceptance criteria, and edge cases for the three API products were written with engineering as part of defining the work, in a format that stayed useful after the ticket closed. The document that told an engineer what to build became the document that told the next engineer why it behaved that way.

Without a business analysis function, that discipline was not optional. If I handed over a spec with holes in it, the holes came back as questions during implementation, and then again six months later as a bug.

Running discovery so the writing had something to say

I ran continuous discovery with engineering and platform partners to validate feature ideas before committing delivery effort. That reduced rework across the three API products, and it had a side effect I did not expect. The questions partners kept asking told me exactly which parts of the product were under-documented. Every integration question that reached us was a gap in what we had written down, pointing at its own location.

Keeping it alive with rituals

I established and facilitated weekly cross-functional rituals with staff engineers, designers, and senior leadership, run in Miro. Priorities, tradeoffs, and decisions were made in the open and written down in the same session. A decision that never reaches a document is a decision that gets re-litigated in four months by people who were not in the room.

What shipped

A documentation framework covering the three core API products — billing, publisher, and advertiser — serving 20+ large-scale platform partners. Onboarding paths for new joiners, implementation-ready requirements and acceptance criteria for engineering, and a single home for every fact that used to live in someone's memory.

What worked

Writing for the reader's task instead of the author's convenience. Making documentation a byproduct of specifying work rather than a separate chore. Enforcing one source per fact, which is the only rule that survives contact with a busy quarter.

What I'd do differently

Instrument it earlier. I know the framework worked because onboarding collapsed from six months to one, but I was measuring the outcome rather than the pages. Knowing which documents were actually opened would have told me what to cut, and cutting is the part everyone skips.