At work I built an internal documentation application that consolidates the auto-generated documentation for our codebase into one interface. The goal was to get a new engineer productive on a large, unfamiliar test automation codebase in their first week rather than their first month.

What I didn't expect was how much the same tool would do for AI assistants. It turns out that a good onboarding path and good assistant context are almost the same artifact.

The problem with legacy onboarding

Legacy codebases accumulate knowledge in the wrong places. The reason a helper exists is in a commit message from years ago. The rule about which fixtures are safe to modify is in someone's head. The auto-generated API docs exist but nobody reads them because they're a directory of a thousand pages with no path through them.

New engineers get a tour from whoever has time, take notes, and spend weeks reconstructing the map. Every one of them builds a slightly different map. I can't publish the codebase, but I can describe the shape of the fix.

An app, not more pages

The instinct is to write more wiki pages. The problem isn't a shortage of pages. It's the absence of a path through them.

The documentation app puts three things behind one interface: the generated codebase documentation, organized by the modules a new engineer will actually touch first; the team's AI configuration artifacts, the Rules, Profiles, and Prompts we use daily; and the working guidance for common tasks, like triaging a failed regression run. Search across all of it. A starting point that isn't "here's the repo."

The effect on onboarding time was measurable. The effect I care more about is consistency: two people onboarded a month apart now hold the same map.

The dual audience

Here's the part that changed how I think about documentation.

When I pointed an assistant at the same consolidated docs, its output on the codebase improved in the same ways a new engineer's did. It stopped proposing patterns the codebase doesn't use. It found the right helper instead of writing a new one. It respected the fixture boundaries because they were written down where it would read them.

That shouldn't have surprised me. An assistant starting a session is a new engineer with no memory. Everything that helps the human on day one helps the assistant on every day. So the documentation app became, in practice, the team's context engineering layer, and the two goals stopped being separate projects.

What's worth indexing

Not everything. The things that pay off:

  • Entry points. Where a test run starts, where a page object is registered, where configuration is read. The places a newcomer has to find first.
  • Boundaries. What must not be modified without a conversation. Shared fixtures, environment config, the adapter layer.
  • Decisions. Why the thing is the way it is, so nobody re-argues it. On this site that's a decision log with numbered records; at work it's a section of the app.
  • Task recipes. The five things people do every week, as short guides that reference the rules.

Auto-generated reference docs are the raw material. The index is what makes them usable.

The same pattern on my own projects

This site has its own version. docs/DOCUMENTATION_MAP.md is the single index into the rest of the documentation. docs/ONBOARDING.md is the path for a person. CLAUDE.md is the path for an assistant, and it points at the same architecture documents. When I reviewed the site recently and found that the two paths had drifted, wrong emulator ports in one, a deleted file still referenced in another, the fix was the same as it would be at work: one index, one source of truth, and a rule that behavior changes update the doc that describes the behavior.

The legacy corners of this site made the point sharply. The portfolio page is a 2015 jQuery build, and the onboarding for an assistant working on it had to say so explicitly: here is what's archived, here is what's current, here is what must stay live for the timeline and what must not be held to the current lint bar. That note is onboarding and context at the same time.

The leadership angle

Building the documentation app was the point where my role at work shifted from individual contributor toward enabling the team. The lever wasn't knowing the codebase better than anyone else. It was making that knowledge not depend on me. Gatekeeping expertise looks like job security and functions like a bottleneck. Making the codebase legible to the next person, and the next assistant, is the move that pays off, and it compounds.

If a codebase can only be understood by talking to a specific person, it can't be worked on by an assistant either. Fixing one fixes both.