Technical documentation style guide (SaaS ERP, brand-neutral)
Internal engineering docs use vendor-neutral product language unless a page is explicitly marked for legal or customer-facing use.
1. Product and platform naming
- Default product name in prose: SaaS ERP (or “multitenant SaaS ERP platform” where clarity helps).
- Avoid in running prose: vendor-specific marketing names, public marketing domains, and GitHub organization labels — use the placeholders below instead.
- Code and configuration literals (package names, env keys, Wrangler identifiers, repository folder names) stay verbatim inside fenced code blocks or inline
`backticks`so readers can copy/paste without breaking builds.
2. Placeholder table (copy for your deployment)
| Placeholder token | Meaning |
|---|---|
PRIMARY_WEB_DOMAIN | Public marketing / product web entry host |
ADMIN_WEB_HOST | Operator or tenant admin web host |
GATEWAY_PUBLIC_URL | Public HTTP API base URL for the edge gateway |
GITHUB_ORG | Source control organization or owner |
MONOREPO_NAME | Main application monorepo directory name |
GATEWAY_REPO | API gateway / OpenAPI repository name |
Document relationships (“admin web calls the control-plane Worker”) without embedding production host strings in prose.
3. Legal and customer-facing exceptions
- Contracts, invoices, copyright lines: use the legal entity name supplied by your deployment (do not invent).
- If a page must show a literal URL for operators (for example CI secrets documentation), confine literals to an Operations appendix section and mark it as environment-specific.
4. Cloudflare vocabulary
Align prose with current Cloudflare product language and each repository’s Wrangler configuration (prefer wrangler.jsonc where the repo uses it):
- Workers (do not use legacy “Workers Sites” wording for Workers-only deploys).
- Cloudflare Pages and Functions where the app uses Pages.
- R2, D1, KV, Queues — name the product when referring to the binding type.
Zuplo is a separate API gateway product; describe it as “API gateway” or “Zuplo” without implying it is a Cloudflare product.
5. Links to other repositories
Prefer role-based references (“gateway OpenAPI repository”, “control-plane Worker repository”) plus placeholders. Raw https://github.com/... links may remain in footnotes or appendices when required for contributor onboarding; avoid repeating them in every paragraph.
6. MDX safety (Starlight)
Sequences like client-web wrapped in angle brackets can be parsed as JSX. Prefer fenced code, inline `...`, or UPPER_SNAKE tokens without angle brackets in prose. See the monorepo docs tree README.md (next to this Starlight app) for MDX authoring notes.
7. Relation to other pages
- The Platform hub points readers here for technical naming.
- Repository-specific environment variable catalogs remain in each repository’s
README.md/AGENTS.md.