Architecting a federated documentation site
aggregating docs from many repos into one site.
docs-as-code with a manifest, CI publishing artifacts, a build that pulls and merges, unified deploy.
manually copy-pasting docs between repos with no automated aggregation.
What's really being asked
This evaluates system design for documentation owned by independent teams, balancing autonomy with a single coherent reader experience.
The full answer
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.
The mistakes people make
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.
What usually comes next
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?
A 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.
Interview question
In a federated docs site sourced from several repos, why publish a versioned content artifact from each repo rather than fetching its docs live at runtime?
- a.Artifacts pin docs to released versions and avoid breakage if a source is unavailableCorrect
- b.Runtime fetching is impossible in any web framework
- c.Live fetching always violates accessibility standards
- d.Artifacts remove the need for any central build step
Why? this is the answer
Versioned artifacts let the site build deterministically against released content and stay up even if a source repo is down. Runtime fetching is possible but couples site availability to every source and risks doc-versus-code drift.
Just read this? Test yourself on what you have been reading.
Read the original → backstage.io
- #documentation
- #architecture
- #docs-as-code
- #ci-cd
- #static-site
You just looked this up. Could you explain it out loud?
That is the part interviews actually test. Tezvyn takes questions like this one and gives you what the interviewer is really checking, the answer that lands, and the mistake that ends the conversation, in the four minutes before your next meeting.
The iPhone app is on the way
We are building it. Until it lands, nothing here is held back from you: every interview card, your saved cards, streaks and the job board all work in Safari, plus hundreds of free practice quizzes of thirty questions each. Sign in and it all carries over to the app the day it arrives.
Want it as an icon? Tap Share at the bottom of Safari, then Add to Home Screen. It opens full screen and the cards you have read stay available offline.
We are hiring for this. Open roles that interview on documentation — each one lists the topics its interview covers.
See open roles