Architecting a federated documentation site

WHAT THIS TESTS This evaluates system design for documentation owned by independent teams, balancing autonomy with a single coherent reader experience.

A GOOD ANSWER COVERS Adopt docs-as-code so each repo, tokens, React components, and content guidelines, owns its docs beside its source. Each repo's CI publishes a versioned, self-describing content artifact, for example a tarball or package containing markdown or MDX plus a metadata manifest describing navigation, version, and ownership. A central documentation build consumes these artifacts, ideally pinned to released versions, merges their navigation trees into one information architecture, applies a shared theme, and renders a static site. Deploy atomically to a CDN, generate preview deployments per pull request, and trigger rebuilds when any source publishes a new version, often via a webhook or a scheduled aggregation. Tools like Backstage TechDocs or a custom Astro or Docusaurus pipeline fit this model.

COMMON WRONG ANSWERS Manually copying docs into one repo. Forcing everything into a monorepo, which contradicts the federated requirement. No per-source versioning, so docs and shipped code drift. A runtime fetch that breaks the site when one source is down.

LIKELY FOLLOW-UPS How do you version docs alongside released packages? How do you handle a source repo being unavailable at build time? How do you keep search working across sources?

ONE CONCRETE EXAMPLE The components repo tags version 3.2.0 and CI publishes a docs artifact with a manifest. The central builder pulls the tokens, components, and content artifacts, merges their nav into one sidebar, themes them identically, builds a static bundle, and deploys to a CDN. A unified search index is generated at build time across all three sources.