Two documentation sites: end-user docs and engineering docs

Status: accepted

Date: 2026-07-10

Relates to: ADR-0031 (unified TS release/versioning/tooling standard — fixes docs/adr/ as the canonical, in-place ADR location), CONTEXT.md → “Structure and identity” (the canonical vocabulary all documentation is written in), .claude/rules/lms-domain.md (corrected by this lane: the one-vocabulary rule extends to all end-user copy, including docs).

Context

Emergent needs user documentation for four audiences: developers/sysadmins operating the software, admins administering an instance, teachers, and learners. The pgxsinkit docs stack (Astro Starlight, starlight-llms-txt, brand CSS, content in src/content/docs/) is the established authoring setup in the sibling repos and is the requested baseline.

The four audiences split cleanly into two registers. Admin/teacher/learner documentation is task-oriented product documentation, written in the canonical neutral vocabulary, destined to be public once a proper corporate site exists. Developer/sysadmin documentation’s audience is exactly the audience of the existing docs/ engineering tree (~139 files: adr, architecture, conformance, design, runbooks, integration, patterns, backlog) — but that tree includes contributor working documents (build plans, lane analyses, backlog) that must never ship publicly.

A single site was considered first, then a single site with a curated engineering subtree. Curation turned into a per-directory (eventually per-file) publish/withhold knife-fight with a permanent risk of leaking workshop material onto a public site.

Decisions

1. Two Starlight sites, split by register, not one site with four sections.

   • apps/docs — end-user site: three areas by reader activity (Administer / Teach / Learn). Fresh task-oriented content only; zero engineering content. Gets the durable docs.… name (the hostname VITE_DOCS_DOMAIN already plumbed through the build pipeline) and is the site that later fronts the public/corporate presence.
   • apps/docs-eng — engineering site for developers/sysadmins: publishes the entire docs/ tree, including design/ and backlog/ (the site is internal; a rendered view of the workshop is useful), plus a written “start here” layer (dev environment, repo tour, deploy/operate guides). Hostname docs-eng.…; chart values key docsEng.
   • The split makes both publication stories trivial: the end-user site goes public untouched; the eng site needs no exclude list because internal is its premise. Each site emits its own llms.txt, so an AI assistant pointed at end-user docs never ingests internal lane history.

2. docs/ stays canonical, in place; the eng site is a generated view. A pre-build step syncs docs/** into a gitignored content subtree and injects the frontmatter Starlight requires (titles derived from existing # headings), failing the build on unreadable files. Nothing moves: the cross-repo ADR standard (ADR-0031), oxfmt exclusions, and existing relative links keep working. (pgxsinkit publishes only a generated ADR index linking to GitHub; that works for a public repo — emergent’s is private, so the eng site renders full text instead.)

3. Internal = per-environment enablement, no auth machinery. Both sites deploy in-cluster as static -data bundle images via the unified Argo build path, with entries in the emergent chart. docsEng is enabled only in dev/internal environments’ values; any future public-facing environment simply never deploys it. Environment membership is already the access boundary in this repo’s posture; gateway-level auth can be added later without touching the site.

4. All documentation is written in the canonical vocabulary (CONTEXT.md → Structure and identity) — teachers and learners read “Offering” and “Learning Unit”, never “Course”/“Module”/ “Lesson”. The stale .claude/rules/lms-domain.md claim that the _Avoid_ words were UI display labels is corrected as part of this lane.

5. No stub pages, no vaporware. v1 ships the full information architecture plus real end-to-end core-loop guides per area (Administer: scope and sign-in, Organization identity, provisioning people, identity review; Teach: Learning Unit tree, authoring/assigning an Assessment, gradebook; Learn: joining an Offering, working through Learning Units, progress). Guides document only flows the shipped UI actually exposes — in-scope flows found missing from the product are recorded as gaps, not written as pages. Anything not yet written is simply absent — an empty page erodes trust in the whole site. Feature lanes grow the docs as they land.

6. i18n-ready from day one, English root locale only on the end-user site (Starlight defaultLocale/locales configured now; adding a locale later is an additive subtree with built-in fallback, not a URL-breaking restructure). Docs locales will track product locales, not lead them. The eng site stays flat English.

7. Branding is a deliberate placeholder. End-user site mirrors the product theme (packages/ui/src/theme.ts: pine primary, Hanken Grotesk, Spectral headings, IBM Plex Mono) with the round “Emergent English Education” badge as favicon/logo mark beside a plain-text title. No links to the current corporate site, nothing NZ-specific; assets swap when the corporate identity refresh lands. Eng site stays essentially stock Starlight. No TypeDoc on either site (emergent publishes no packages).

Consequences

• Two Astro apps to build and keep current instead of one; both join the turbo format/lint/typecheck/build lanes and the unified Argo build path (docs-data, docs-eng-data images).
• Engineering docs gain a rendered, navigable, llms-txt-indexed view with zero migration and no new writing obligations; the end-user site’s quality bar is decoupled from the workshop floor.
• Cross-site links (end-user → eng) are external URLs, deliberately rare, and unresolvable for readers without dev-environment access — acceptable, since the end-user site must stand alone for its audience anyway.
• When the corporate site lands, publishing the end-user docs is a hostname/values change, not a content audit.