Product surfaces are carrying documentation because there is nowhere else to put it. The clearest case is the FerrVault operator-token dialog: app/src/app/shared/connect-cluster-wizard.ts is 773 lines, and most of it is Helm commands, CRD manifests, a CLI walkthrough and a GitHub Actions snippet, rendered inside a modal that exists to show a token once. app/src/app/pages/k8s.ts adds another 590.
The shell for the alternative already exists and is unused. Every product site has a /docs route, and @ferrlabs/ui-ng/docs ships the whole engine: sidebar, section nav, in-page TOC, prev/next pager, .ferr-prose content styles, FR/EN. Only FerrFlow-Cloud consumes it, with 171 markdown files. Everywhere else:
| Site |
/docs today |
| FerrFlow |
real, 171 files, versioned, content in the FerrFlow-Docs repo |
| FerrVault |
<h1>Coming soon.</h1> |
| FerrTrack |
<h1>Coming soon.</h1> |
| FerrGrowth |
one hand-written page, 77 lines, no engine |
| FerrFleet |
one hand-written page, 66 lines, no engine |
| FerrLens |
no docs index at that path |
Decisions
Markdown lives in each Cloud repo, under site/src/content/docs-en and docs-fr, not in a docs repo per product. The org rule is already that code and docs ship together; keeping the markdown next to the code that changes it is the only way that holds. FerrFlow keeps its separate repo, which earns it: its docs are frozen per CLI major, and a public repo takes outside contributions.
The engine is wired everywhere first, content follows. Each site gets docs-nav.ts, a DocsPageComponent, the [[...slug]] content route, the stylesheet import, prerender and sitemap entries, and one real introduction page in both languages. That is a working docs section with one page in it, rather than five half-written manuals landing at once.
No version picker outside FerrFlow. These products ship continuously; flr-docs-layout takes an empty versions list and hides it.
Then
With somewhere to put it, the in-app explanations move out: the FerrVault wizard keeps the token and a link, and the manifests, the flags and the failure cases become pages. Same treatment for anything else that grew a tutorial inside a dialog.
One PR per repo, each referencing this issue.
Product surfaces are carrying documentation because there is nowhere else to put it. The clearest case is the FerrVault operator-token dialog:
app/src/app/shared/connect-cluster-wizard.tsis 773 lines, and most of it is Helm commands, CRD manifests, a CLI walkthrough and a GitHub Actions snippet, rendered inside a modal that exists to show a token once.app/src/app/pages/k8s.tsadds another 590.The shell for the alternative already exists and is unused. Every product site has a
/docsroute, and@ferrlabs/ui-ng/docsships the whole engine: sidebar, section nav, in-page TOC, prev/next pager,.ferr-prosecontent styles, FR/EN. Only FerrFlow-Cloud consumes it, with 171 markdown files. Everywhere else:/docstoday<h1>Coming soon.</h1><h1>Coming soon.</h1>Decisions
Markdown lives in each Cloud repo, under
site/src/content/docs-enanddocs-fr, not in a docs repo per product. The org rule is already that code and docs ship together; keeping the markdown next to the code that changes it is the only way that holds. FerrFlow keeps its separate repo, which earns it: its docs are frozen per CLI major, and a public repo takes outside contributions.The engine is wired everywhere first, content follows. Each site gets
docs-nav.ts, aDocsPageComponent, the[[...slug]]content route, the stylesheet import, prerender and sitemap entries, and one realintroductionpage in both languages. That is a working docs section with one page in it, rather than five half-written manuals landing at once.No version picker outside FerrFlow. These products ship continuously;
flr-docs-layouttakes an emptyversionslist and hides it.Then
With somewhere to put it, the in-app explanations move out: the FerrVault wizard keeps the token and a link, and the manifests, the flags and the failure cases become pages. Same treatment for anything else that grew a tutorial inside a dialog.
One PR per repo, each referencing this issue.