Documentation pipeline for engineers
Updated
The documentation pipeline is a set of small gates, each protecting one failure mode that already escaped once: wrong-language prose, dead links, stale generated indexes, missing screenshots, invisible pages, and UI labels that do not exist on screen.
Run order in zulo.one#
Run these from D:\Sources\zulo.one when changing wiki or reference sources.
The order is cheap source checks first, then generated drift, then UI wording.
| Order | Command | Protects |
|---|---|---|
| 1 | node tools/check-en-source.mjs |
The source documentation is English. Code, inline examples and short statutory originals are allowed; pasted Russian/Ukrainian/Arabic prose is not. |
| 2 | node tools/check-doc-names.mjs |
Business/user/learn/reference docs do not promise business-layer objects that the workspace no longer has. Developer platform pages are intentionally outside this oracle. |
| 3 | node tools/check-doc-links.mjs |
Relative .md links and same-page anchors resolve in the repository, not only after the site has rewritten routes. |
| 4 | node tools/check-doc-images.mjs |
Every wiki image reference has alt text, an immediate italic caption, resolves under wiki/img, and no stale image file is left unreferenced. |
| 5 | node tools/check-portal.mjs |
Every business/work/developer page is in wiki/portal.json, has a valid zone/group/topic/order, and zone indexes link only inside their zone. |
| 7 | node tools/gen-reference.mjs --check |
The generated business-layer reference still matches the workspace metadata. |
| 8 | node tools/check-guide-keys.mjs |
Literal in-app guideKey values have wiki/guides files, guide defaults are embedded, and the guide tree is not empty. |
| 9 | node tools/audit-ui-labels.mjs |
Bold user-facing labels in wiki/work match English UI strings from frontend/src/i18n/locales/en.ts or workspace captions. The expected miss count is 0. |
build-portal is the only write step in this list. Run it before --check, and
review the generated diff like code: the registry is the source, the generated
blocks are the consequence.
Site gates in getzulo.com#
The site repository answers a different question: not "is the wiki internally
consistent?" but "can a reader reach the page on the public site?" Run these in
D:\Sources\getzulo.com with ZULOONE_REPO pointing at the wiki checkout when
needed.
| Command | Protects |
|---|---|
pnpm check:coverage |
Every tracked wiki/docs page has exactly one fate: published, denied with a reason, delivered elsewhere, or a known shrinking unrouted gap. |
pnpm sync:wiki --check |
The published set and copied content match scripts/lib/wiki-publish.mjs and scripts/published-pages.json; denied internal pages do not leak into public output. |
pnpm check:live |
The deployed site answers every published documentation page, redirects legacy locales correctly, and serves the images the source expects. |
Traps learned#
- Shallow clone dates.
sync-wikireads git history to date pages. A shallow checkout makes every page look changed in the latest commit, so the site workflow usesfetch-depth: 0for the wiki checkout. - CRLF versus LF in generators. Generated blocks are compared on Windows and
in CI.
build-portalnormalizes input to LF before regex replacement; do not reintroduce platform-dependent newline comparisons. - Empty walks must fail. A checker that scans zero files is broken, not green. The docs gates intentionally fail on suspiciously small walks or empty guide trees.
- A new gate must be proven red. When adding a checker, break a known sample or point it at a fixture first. A green-only gate can be checking the wrong root, the wrong language or generated output after the damage is already hidden.
- Site and wiki checks are not interchangeable. Repository link checks catch broken relative source links; site link checks catch rewritten public routes. Run both for release work.
What's not there yet#
audit-ui-labelsis still an audit script rather than a hard CI gate, but the accepted result for user docs is zero misses.- The developer platform wiki has no object-name oracle like business docs do;
engineers must verify platform identifiers against
src/andfrontend/. - The live-site check proves the current deployment, not that a rollout will happen automatically after the repository gates pass.
Where next#
- In-app help — guide keys, tours and field hints that several gates protect.
- The forms system — form-layout text and hints that must stay synchronized with the renderer.
- Platform architecture — how generated platform behaviour is documented without duplicating code.
Was this page helpful?