Copied to Clipboard
README.md': join(process.cwd(), 'docs', 'README.md'),
'API.md': join(process.cwd(), 'docs', 'API.md'),
'ARCHITECTURE.md': join(process.cwd(), 'docs', 'ARCHITECTURE.md'),
'product-manual.en.md': join(process.cwd(), 'docs', 'product-manual.en.md'),
'product-manual.zh-CN.md': join(process.cwd(), 'docs', 'product-manual.zh-CN.md')
});
That mattered for two reasons:
- the UI got a stable set of documents
- the product assistant got a cleaner source of truth
The manual files are now doing real product work
This was the architectural shift that made the cleanup worth it.
The docs are not only for GitHub readers anymore. They are also part of the product behavior.
The product manual now carries the user-facing explanation of:
- dashboard navigation
- routing concepts
- CLI configuration
- channel workflows
- troubleshooting paths
That means the manual has to be shaped for actual usage, not just for repository completeness.
One note in the docs hub says it pretty plainly:
- `product-manual.en.md` and `product-manual.zh-CN.md` are the primary user-facing manuals.
- The product assistant reads from those manual files directly.
Once that became true, letting the README keep absorbing everything stopped making sense.
I also had to accept that maintainers and users need different entry points
This is the trap I keep seeing in open-source docs.
Maintainers are comfortable with:
- roadmap files
- architecture notes
- release checklists
- migration plans
- incident writeups
New users are not.
If those documents sit beside the real onboarding path without any structure, the repo starts feeling harder than the product.
So the current split lets the project keep maintainers' documents in docs/ without making them the front door. The docs hub explicitly calls that out:
Planning, incident, and roadmap documents remain in this directory for maintainers, but they are not the best entry point for first-time users.
That one sentence removed a lot of ambiguity.
What changed for the actual product
The cleanup was not cosmetic. It changed how the project presents itself in three different contexts:
- GitHub readers now get a faster landing path
- dashboard users now get a short manual without leaving the product
- the product assistant now has clearer manual context to answer from
That last one is easy to underestimate.
If you build an assistant into the product, your documentation stops being passive. It becomes runtime input. Structure starts to matter much more than volume.
The pattern I would reuse
If your open-source project is growing past a single README, I think this split is a better default than endlessly reorganizing one giant file:
-
README.md for orientation and quick start
-
docs/README.md as a docs router by audience
- an in-product quick manual for operational tasks
Not every project needs all three.
But the moment your docs are serving both repository readers and product users, pretending those are the same audience usually creates a worse experience for both.
If you want to inspect the implementation, the project is here:
CliGate on GitHub
I'm curious how other people are handling this boundary. When did your README stop being a README and start trying to become the whole product manual?