This is part 1 of a 4-part series on restructuring engineering documentation with an AI teammate.
1. The messy truth about restructuring engineering docs with an AI teammate – you're here
2. Stitching five documentation frameworks into one coherent engineering wiki – [coming soon]
3. Your Confluence should be a derived read model over your repo – [coming soon]
4. Codifying your reorg: playbooks as the shared interface for humans and AI teammates – [coming soon]
Context
We work with Beacon, a mid-size subscription commerce platform. Beacon has been in operation for about seven years and today runs on roughly 20 backend services and around 15 engineers. The engineering wiki has been growing since day one. On the day we opened the audit spreadsheet, the Confluence space held 517 pages.
The trigger was one on-call rotation in which three separate engineers pinged the platform channel asking where the cancel-subscription flow was documented. All three had searched. All three had found different answers. What followed was a six-week restructuring effort, done by one engineer working alongside an AI teammate. This post covers what we inherited, why we chose to restructure the whole space in one push, what worked, and what quietly broke.
What the wiki looked like on day one
A search for "cancel a subscription" returned three top hits: a 2021 page marking the feature as beta behind a flag, a 2023 page pointing at the wrong service, and a 2024 page tagged deprecated pending a rewrite. All three were marked Current. None had been touched in eleven months.
The audit numbers surfaced how far things had drifted:
· 517 pages in total
· Median last-edited age of 2 years and 3 months
· 63 pages still in draft
· 41 pages with zero inbound links, never referenced after creation
Three separate top-level pages competed for the same job (Architecture from 2019, Technical Architecture from 2021, System Design from 2023), each accumulating children in isolation. Ownership was equally uneven: some services had a handful of well-maintained pages, others had one three-year-old page describing an API that had been rewritten twice since.
The behavioural signals were sharper than the numbers. The median engineer had opened Confluence twice in the last month, both times to update a page they already had the URL for. New hires were building parallel Google Docs. On-call engineers kept private Slack bookmarks. The wiki was still growing, just further from the code each week.
Structure over patching
The obvious approach was incremental: pick the ten worst pages each sprint and move on. At that rate, 517 pages is a 26-sprint commitment, a full year of two-week sprints, and every one of those 517 pages continues to drift while you work through them. The first fix would be stale before the last one shipped.
The deeper problem was that the space had no shape. There was no answer to where should this go?, so every new page went wherever its author last looked. Patching one page at a time fixes wrong pages; it does not create a shape.
We chose to restructure the whole space in one push: six weeks, one framework, every page reparented, archived, rewritten, or deleted. Six weeks of two engineers on a docs project is a difficult conversation. Six weeks of one engineer plus AI-assisted work is a different conversation, and it is why the restructure happened at all.
The frameworks, in 90 seconds
The wiki has eight top-level sections. Each is backed by an industry framework, chosen because it fit that section's audience better than the alternatives:
· Architecture uses C4 for system context, containers, and components, plus arc42 for cross-cutting concerns and quality attributes.
· Development uses Diataxis, split into Getting Started, How-To, Reference, and Explanation, with a Spikes and Initiatives folder for in-flight work.
· Team uses the GitLab Handbook pattern for roles, ceremonies, and ways of working.
· Release uses DORA metrics for deployment health.
· Operations uses Google SRE runbooks.
· Support uses blameless postmortems (also from Google SRE) as its primary artifact type.
· Discovery uses Shape Up for pitches and Marty Cagan's four risks for validation.
· Functional is our own convention: a capability-oriented read model layered over the service-oriented Architecture section, added specifically for cross-team readers.
Post 2 covers the full map and the sub-folder conventions.
The division of labour between us and the AI
Once we started dispatching work, the shape of the collaboration got clearer than we expected. It was not AI writes, human reviews. It was more specific.
Framework and taste decisions stayed with us. Which framework fits which section, what the top-level shape should be, which pages get archived and which get rewritten. These are opinionated calls that need context about the company, the team, and the readers. We tried delegating this early and the AI was worse at it than a mid-level engineer would have been. We stopped asking after the first two attempts.
Fan-out went to the AI. Once we had decided that every beacon-labs/<service> repo needed a docs/README.md landing page in a fixed shape, one call dispatched seventeen parallel agents. Each one read its own repo, extracted the actual API surface, and wrote the landing page. We read the seventeen resulting pages; we did not watch each agent work its way through its repo.
Reviewing stayed with us. Every AI-produced page went through a human read before it landed in Confluence. The drafts were usually good; that was not the concern. The concern was that a wrong page that looks wrong gets ignored, and a wrong page that looks right poisons the wiki for years.
Mechanical migration went to the AI. Reparenting 517 pages, updating inbound links, adding children macros, rewriting titles for consistency. This is high-volume, low-judgement work, and agents are good at it. We codified the moves into a playbook — a numbered runbook combining shell commands, MCP calls, and LLM prompts that either a human or an AI teammate can execute step by step (Post 4 covers the pattern) — and ran the migration in batches.
Naming stayed with us. We tried delegating page titles and stopped after the third round of edits.
The interface between us and the AI was always a written plan or playbook, never a Slack thread. Writing the plan forced the ambiguity out of our heads before the AI started, which is where most of the wasted cycles had been coming from.
What worked
Parallel agents for repo landings. One prompt described the target docs/README.md shape; one call dispatched 17 agents in a single fan-out. One afternoon. Every repo came back with a landing page grounded in its actual code. About four needed edits; the rest went in as drafted. Equivalent human effort would have been two weeks of one engineer's time and less consistent, because attention drifts across seventeen sittings.
A mermaid-to-image playbook. Confluence's Mermaid support is unreliable when pages are created via the API, so we render diagrams to PNG in the repo and upload them as attachments alongside the Confluence page. We wrote the playbook once (inventory the diagrams, render, upload, patch, verify) and it now runs against any repo in the group. Post 3 walks through this end to end.
Forks for follow-up work. When we needed a survey answer such as "which pages in the Architecture section still reference the pre-2022 auth flow?", we forked the parent session rather than starting fresh. The fork inherited the map of the space, the framework choices, and the vocabulary. It came back with a punch list in minutes. A fresh agent would have spent half its context re-learning the same setup.
What did not work
Two things bit us hard enough to record.
Subagent sandbox limits. The Bash tool inside a dispatched subagent, on our setup, was restricted to the agent's current working directory. Fine for single-repo work; broken immediately on cross-repo work. When we asked an agent to render diagrams from beacon-labs/catalog-service and upload them from a shared attachments cache in a parent directory, the cp calls were denied. MCP calls kept working because they were over HTTP rather than filesystem-bound. The workaround was to route cross-repo moves through MCP where possible, and to make the CWD the shared parent otherwise.
Page titles drifted from page bodies. Halfway through the migration, a reviewer asked why the analytics vendor was spelled TRENDSENSE on every page. The vendor is called TrendSense, sentence-cased, not an acronym. We had done a bulk body-content rename, and the AI had faithfully rewritten every occurrence inside page bodies. It had not touched the page titles, which still read TRENDSENSE integration overview, TRENDSENSE cohort feed, and so on. The bodies said one thing; the titles said another; the sidebar tree looked, to any casual observer, exactly as wrong as before we started.
The fix was mechanical once we noticed. Noticing took two weeks. The lesson we now bake into every prompt: if you rename in bodies, also enumerate and rename titles, and treat title drift as a first-class review checkpoint.
Results
At the six-week mark, 517 pages became 312. 148 pages were archived; 57 were merged into other pages. Every remaining page sits under one of the eight top-level sections. Every sub-folder parent has a description and a children index that actually renders. Every service has a landing page grounded in its own repo.
Drift was eliminated in the sections we touched heavily (Architecture, Development, Operations, Release). Discovery and Support are lighter and mostly manual; we did not restructure them aggressively, and we are honest that they will drift again. On the on-call test we care about most (open the wiki, find the right runbook for a given alert), median time dropped from over a minute to under fifteen seconds.
If we were doing it again, the one thing that would change on day one is title enumeration before any bulk body rename. The TrendSense fix cost three days we did not need to spend.
Where the series goes from here
Coming next: Stitching five documentation frameworks into one coherent engineering wiki. Post 2 lays out the eight-section top-level map, the combination-of-frameworks logic behind each section (C4 + arc42, Diataxis + Spikes, GitLab Handbook, DORA + SRE, Shape Up + Cagan).
