Framework onboarding manual

Why this is here and the document is not

The manual documents a proprietary in-house build framework: its layout partials, component structure, configuration and build pipeline. That is the agency’s intellectual property, not mine to publish, so this page describes the work without reproducing it. What follows is the thinking, not the contents.

I should also be precise about what I did and did not build. I did not write the framework — that is a colleague’s work, and the credit is his. I wrote its manual.

The problem

Onboarding ran on people. A new developer’s first week meant sitting next to someone who knew the framework, asking questions as they came up, and accumulating knowledge in whatever order the questions happened to arrive. It worked, and it cost two developers instead of one every time.

It also concentrated risk. The number of people who could answer a question about the build configuration was small enough to count on one hand, and every one of them was busy. That is a bus-factor problem wearing a training problem’s clothes.

What the manual had to do

Two readers, not one. Somebody in their first week needs a path: install this, run this, here is what a unit looks like, here is how to make one. Somebody in their third year needs a lookup: what does this configuration field do, what does the build emit, which plugin is available. The same document has to serve both without the second reader wading through the first reader’s hand-holding.

I split it accordingly. The opening sections run as a path, in order, with the commands you actually type. Everything after is organised for lookup — one section per subsystem, addressed by what you are trying to find rather than by how the code happens to be arranged.

The examples are real. Every code sample is a working excerpt rather than a paraphrase, because a manual that has been paraphrased into approximate correctness is worse than no manual: it costs the reader the time to discover they have been misled.

English and Spanish

The team spans both. Writing it once in English and leaving the Spanish speakers to translate as they read would have quietly taxed half the team on every lookup — which, over a year of lookups, is not a small tax. Both versions ship together, and both are maintained.

Where AI fits

I produced the manual with AI assistance, and I would say so in an interview without hesitating. The useful framing is what the assistance did and did not do: it accelerated drafting and kept the structure consistent across seventeen sections. It could not tell me which configuration fields the team actually gets wrong, which build step breaks most often, or which explanation finally makes the timeline patterns click for someone new. That came from having built in the framework, and from watching people struggle with it.

The judgment is the part that is mine. The typing was always the cheap half.

What it changed

Onboarding stopped being a two-person activity. A new developer can now get to a first working unit from the document, and use the senior developer’s time on the questions the document does not answer — which are the questions worth a senior developer’s time.

The other thing it changed is more selfish and worth admitting: writing down how something works is the fastest way to find the parts you only thought you understood. Several sections took three attempts because the first two were me discovering I could not actually explain the thing.