| name | docs-as-code-at-scale |
| description | Use when applying Documentation-as-Code across many teams or a super-app / multi-repo / monorepo with several mini-apps — how to lay out per-team docs, own API contracts at boundaries, keep one traceability matrix across teams, and run the gate per changed area. The advanced (Lesson 6) counterpart to single-project docs-as-code. |
Docs-as-Code at Scale
Single-project docs-as-code is the lifecycle skill's job. This skill is for when many teams
share an ecosystem — a super-app shell with mini-apps, a monorepo with packages, or several repos —
where the hard problem is not authoring a doc but keeping ownership and traceability coherent across
boundaries. This is the Lesson 6 capstone made operational; the worked reference is
examples/nova-superapp/.
Layout: docs co-located with the thing they describe
Each team/mini-app keeps its own docs/product-docs/ next to its code (e.g.
mini-apps/<team>/docs/), so ownership is obvious and a change touches docs + code together. A
thin top-level docs/ holds only ecosystem-wide artifacts (the shell BRD, cross-cutting NFRs) and
the aggregated traceability view.
Contracts own the boundaries
Where two teams meet, a contract is the single source of truth — the provider owns it, consumers
point at it and never re-describe the fields. This is what prevents the "added a required field and
broke a consumer" incident. Keep contracts in a shared contracts/ directory so every consumer can
find them; the contract's consumers frontmatter drives who must review a change. Use the
contract-breaking-detector agent on any contract diff.
One traceability matrix, several owners
Run docs-as-code:trace across the whole tree so the matrix spans teams: add Mini-app and
Contract columns so you can see which team owns a thread and who consumes which contract
(filtering by a contract gives you its migration list). A requirement in one mini-app verified by a
test in another still shows as a complete chain — that cross-team link is the point.
Gate per changed area, not the whole world
A big monorepo should not re-validate everything on every PR. Detect which mini-apps/contracts
changed and run docs-validate.sh + docs-trace.sh --check on those paths, plus
check-contracts.sh always (a contract change can break a team that did not touch its own files).
See the illustrative pipeline in examples/nova-superapp/.github/workflows/validate.yml.
Principle
At scale the failure mode shifts from "missing doc" to "boundary drift" — a contract and its
consumers diverging silently. Co-located ownership + contracts at boundaries + one cross-team matrix
- a per-area gate keep the ecosystem honest.
