Stitching five documentation frameworks into one coherent engineering wiki

This is part 2 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 – link

2. Stitching five documentation frameworks into one coherent engineering wiki – you're here

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]

Why one framework is not enough

There is no shortage of framework retrospectives. Sequin wrote a widely-read post on how they fixed their documentation with the Diataxis framework. Bitsmuggler's arc42+C4 example repo is the canonical worked example for combining those two. Every framework we picked has at least one thoughtful writeup behind it, and we read most of them before starting.

None of those posts covered what we needed. Each retrospective goes deep on one framework in one section of a wiki. Diataxis is well-suited for tutorials and reference; it says nothing about how architecture pages should be structured. C4 is excellent at architecture; it makes no claims about how team ways-of-working should be filed. Pick one framework and you cover one section well and stare blankly at the other six.

An engineering wiki serves at least seven distinct audiences: the new hire on day one, the on-call engineer at 3 a.m., the staff engineer scoping a spike, the engineering manager onboarding a report, the release engineer answering "how did we do this quarter?", the product manager sketching a bet, and the support engineer chasing a customer incident. Each has a different framework already written for their slice of the wiki. What was missing was the map that connects them.

This post is not another Diataxis endorsement or another C4 walkthrough. It is how we stitched five-plus frameworks into one coherent top-level shape with Beacon, and the sub-folder conventions that stopped the seams from tearing.

The eight-section top level

The Confluence space had, on day one of the reorg, no consistent top-level. Three variants of Architecture, two variants of Ops, and one Miscellaneous folder holding 71 pages. We landed on eight top-level sections, chosen up front and unchanged through the six weeks. The point of each section is that every wiki page has exactly one obvious home.

1. Discovery for what we might build, and why. Product bets, unscoped spikes, competitive research.
2. Architecture for how the system is put together. Services, containers, cross-cutting concerns, quality attributes.
3. Development for what an engineer does day-to-day. Onboarding, how-tos, references, in-flight initiatives.
4. Team for who we are and how we work. Roles, ceremonies, ways of working, the on-call rota.
5. Operations for the runtime knowledge an on-call engineer needs at 3 a.m. Dashboards, cheat-sheets, incident procedures.
6. Release for how we ship. Release trains, DORA metrics, per-sprint runbooks.
7. Support for what happens after something breaks. SRE practices, blameless postmortems, incident library.
8. Functional for capability-oriented reads across services. More on why we added this section alongside Architecture below.

Per-section framework choice, with rationale

Here is the map, one section at a time, with the framework we picked and why.

Discovery uses Shape Up and Cagan's Four Risks. Shape Up gives us pitches, appetites, and hill-charts as a shared vocabulary for in-flight bets. Cagan's Four Risks (value, usability, feasibility, viability) become the pitch template's mandatory sections. A pitch page that skips feasibility is visibly incomplete, which is the point.

Architecture uses C4 and arc42. C4 owns the diagrams: system context at the top, containers below, components on demand. arc42 owns the prose sections C4 does not: cross-cutting concerns (auth, observability, resilience), quality attributes as a testable list rather than aspirations, and architecture decisions. C4 and arc42 fit together cleanly because they solve different problems. C4 is a diagramming convention; arc42 is a section skeleton. Bitsmuggler's example was the confirmation we needed that the pairing works in practice.

Development uses Diataxis, plus Spikes and Initiatives. Diataxis's four quadrants (tutorials, how-to, reference, explanation) cover the steady-state developer surface. We added Spikes and Initiatives as fifth and sixth folders because in-flight work does not fit any of the four quadrants, and forcing it in makes both the in-flight page and the quadrants worse. A spike ends and its page either graduates into a Diataxis quadrant or gets archived.

Team uses the GitLab Handbook. GitLab's public handbook is the most rigorous example we know of how a company works documented as living code. We stole the section shape: roles, ceremonies, ways of working, on-call rota, career ladders. Not the volume, though. GitLab's handbook is a mid-size book. Just the shape.

Operations uses an engineer-runtime cheat-sheet pattern. This is the one section without a named external framework. Operations is what an on-call engineer needs when the pager goes off: a dashboard link, a break-glass procedure, a one-page cheat-sheet per service. We looked hard for prior art and found only Google's SRE book, which is philosophy rather than a sub-folder structure. So we invented a shape and called it what it is: a cheat-sheet pattern, not a framework. Being honest about the boundary between borrowed and invented mattered to us. Pretending we had a framework here would have been the exact kind of hedge Post 1 promised not to make.

Release uses DORA and per-sprint runbooks. DORA (deployment frequency, lead time, change failure rate, MTTR) gives us the metrics section. Per-sprint runbooks (one page per release train per sprint) give the executional detail. Post 3 shows how these are derived from repo-side data rather than typed into Confluence by hand.

Support uses Google SRE and blameless postmortems. SRE gives us error budgets, SLOs, and the incident-response vocabulary. Blameless postmortems give us the incident library. Every postmortem uses the same template, which means the library scans as a coherent set rather than seventeen personal essays.

Sub-folder conventions across every section

The below conventions apply to every sub-folder in every section. They sound trivial until you skip them.

Hyphen suffix on title collisions. Onboarding means one thing under Team (a new hire's first month) and something different under Development (setting up your laptop). Both pages exist; both need distinct titles because Confluence's global search does not respect ancestry. We suffix with a hyphen and the section: Onboarding – Team and Getting Started – Development. Ugly, unambiguous, and searchable.

Single-child collapse. If a sub-folder has only one child, delete the sub-folder and promote the child. Architecture / Cross-cutting concerns / Auth / Auth overview becomes Architecture / Cross-cutting concerns / Auth overview. Single-child sub-folders are almost always aspirational shells that never got their siblings. They add depth and hide content. Collapse aggressively.

Why Functional sits alongside Architecture

Architecture organises the wiki by service. That serves engineers well and cross-team readers badly. A product manager investigating "what does our subscription capability actually do?" would land in Architecture, hit subscription-service, subscription-lifecycle-orchestrator, and billing-service, and have to reconstruct the capability from three service pages.

Functional is our audience-lens sub-tree, distinct from the framework-lens seven. Each Functional page describes one product capability (Subscriptions, Checkout, Fulfilment) with links out to the services that implement it. It duplicates nothing; it composes. The read model is derived, which is the topic of Post 3.

The lesson: a framework-driven top level is engineer-centric by construction. If your wiki serves anyone else (PMs, customer success, sales engineers), add an audience-lens section explicitly from day one. Do not try to make Architecture do that job. It cannot.

What we deliberately left out

Customer release notes live in the product marketing space, not Engineering. Sales enablement material lives with Revenue Ops. Marketing-as-docs, the polished funnel-oriented content, lives on the public site. All three came up during scoping and all three were declined. Engineering docs serve engineers first. Every cross-purpose page in the wiki is a page nobody owns.

The temptation to make one wiki serve every audience is the same temptation that produced the original 517-page mess. Resist it.

The full map

The eight sections and a sample of the sub-folders under each:

Coming next: Your Confluence should be a derived read model over your repo. Post 3 introduces the per-repo structure that pins every Confluence page to a repo path, the reconciliation loop that keeps the round-trip honest when someone edits Confluence directly.