I keep running into the same question in multi-repo systems:
Read the thread on XShould architecture docs live per repo, or at the system level?
Docs per repo… or docs to rule them all?
What this post is
A practical answer to that tradeoff, anchored on a concrete microservices example (Sock Shop). This isn’t a benchmark—just a pattern we’ve found useful for keeping docs usable for humans and AI agents.
Why this tradeoff is real
Multi-repo docs fail in two opposite ways: fragmentation and fiction.
Docs per repo
- →Close to code; easier to keep accurate
- →Great for local build/run/debug
- →System truth gets fragmented across 10 READMEs
- →Cross-service flows are hard to reconstruct
Docs to rule them all
- →Builds a shared mental model fast
- →Best place for cross-service flows
- →Drifts into fiction unless maintained
- →Hard to keep “close to code”
The trap is trying to make one doc style do both jobs: orientation and completeness.
A docs stack that works in practice
Rule of thumb
System docs should be guide-first (orientation), while repo docs should be reference-first (how to run/ship). The goal is to reduce context loss—without pretending one document can be the “complete truth.”
Why Sock Shop is the perfect test
Sock Shop is the “hello world” of microservices, but it’s real enough to stress the docs problem: multiple services, multiple data stores, async messaging, and cross-service user flows.
System-level docs should answer
- →What are the boundaries? (catalogue, carts, orders, users, front-end…)
- →How do flows traverse services? (add-to-cart → checkout → order)
- →Where are the risk points? (retries, idempotency, coupling, outages)
Repo-level docs should answer
- →How do I run it locally and validate changes?
- →What contracts does it expose/consume? (APIs, events, schemas)
- →What’s the deployment/ops reality?
In practice, generating a usable “system guide” from a multi-repo codebase takes about 30–60 seconds in our current alpha flows. The interesting part isn’t speed—it’s what you choose to show first.