Your Monorepo Is Not the Problem
Strategies for documenting products split across multiple repositories or a monorepo, and how multi-repo projects keep one coherent help centre.
The documentation for a feature that spans three services lives in whichever repository the person writing it happened to have open. The billing explanation ends up in the API repo because that is where the webhook handler is. The part about what customers see is in the frontend repo. Six months later somebody asks where the billing docs are and the honest answer is "which half?"
The instinct is to blame the repository layout. It is almost never the repository layout.
Repo boundaries are engineering seams, not user seams
Your repositories are divided along lines that made sense for deployment, ownership and build times. Those are good reasons and they have nothing whatsoever to do with how a customer experiences the product.
A user does not know that the thing they are doing crosses four services. They know they clicked Export and got an email twenty minutes later. The article that explains that spans your entire architecture and belongs to none of it, which is why filing documentation by repository produces a table of contents that reads like an org chart.
The same applies in reverse for a monorepo. Having everything in one repository does not make the documentation coherent - it just moves the problem from "which repo" to "which directory", and packages/billing/docs is exactly as arbitrary a home as a separate repo was.
So the structural question is not how to mirror your code layout in your docs. It is how to stop mirroring it at all.
Section structure comes from tasks, not from services
The help centre's top-level structure should be derived from what people are trying to do. Getting set up. Working with teams. Billing and plans. Troubleshooting. Those categories are stable across redesigns and re-architectures precisely because they are about the user's intent rather than your deployment topology.
Underneath that, an article can draw on as many repositories as it needs. In SupportPages a project connects several repositories and produces one help centre - the analysis runs per repository, the article inventory and section structure are per project. That is the shape I would recommend even if you were doing all of this by hand: analyse per codebase, organise per customer.
The practical consequence is that "which repo does this article belong to?" stops being a question anybody asks. Articles belong to sections. Sections belong to the product.
The genuinely hard case
Where this gets difficult is not many repositories. It is many products pretending to be one.
If you have acquired something, or grown a second product with a different audience and a separate sales motion, one help centre is usually the wrong answer regardless of how the code is laid out. Shared navigation means every visitor wades through articles about a product they do not have, search returns results from the wrong context, and the AI answer layer confidently explains a feature that exists in the other product.
The test I use is the audience rather than the code: if a typical customer of A would never use B, they are separate help centres. If most customers touch both, one help centre with clear sections is right even if the code lives in fifteen repositories.
When mirroring your architecture is correct
Task-based structure has a real failure mode, and it is worth naming because it is the mirror image of the problem I have just described.
Some products genuinely are used by two different populations. A platform with an admin who configures things and end users who consume them has two intents, two vocabularies and two mental models. Forcing those into one task hierarchy produces sections where half the articles are irrelevant to whoever is reading, and the honest fix is to split by role even though that means duplicating some navigation.
There is also the case where your users are engineers who do think in services, because they integrate with your services individually. Then mirroring your architecture is not a mistake - it matches how they reason. That is generally reference documentation rather than a help centre, and reference documentation should be generated from schemas and live next to the code.
The check
Open your help centre's top-level navigation and ask whether someone who has never seen your codebase could have written it.
If the answer is no, it was written from the inside out.
About the Author
Simon Moxon has been building SaaS companies since 2009. He's scaled teams to 20+ people, hit £2m ARR, and learned most of the lessons the hard way. Now he's building SupportPages.io - help docs that write themselves when you ship code. He writes about what's changed in SaaS and what hasn't.