Project Manager Guide — Docs-Site

This guide explains the documentation platform from a project management perspective: the problem it solves, the value it delivers, how governance works, and how to plan documentation work within the Registry Platform.

Table of Contents

• The Problem It Solves
• The Value Proposition
• The Two Documentation Sites
• Content Governance Model
• How to Request New Documentation
• Quality Indicators
• Scalability — Adding New Docs Sites
• Risks and Mitigations
• Summary

---

The Problem It Solves

Before this system existed, the Registry Platform had documentation scattered across:

• Inline README files in individual service repositories
• Partial VitePress and Next.js sites with diverging content
• Team wikis that were updated inconsistently

This created three persistent problems:

Content drift. The same topic (e.g., how to authenticate) had different instructions in different places. Users could not tell which version was correct. Developers lost time reconciling conflicting docs.

Double maintenance overhead. Every documentation update required editing multiple files in multiple locations. Updates were frequently applied to one site and forgotten in others.

No clear ownership. Without a single source of truth, it was unclear which file was authoritative when two copies disagreed.

graph TD
    subgraph before ["Before: Scattered Docs"]
        wp["VitePress copy\nauth guide v1"]
        nx["Next.js copy\nauth guide v2"]
        rm["README copy\nauth guide v1.5"]
    end

    subgraph after ["After: Single Canonical Source"]
        canonical["docs/docs-site/guides/authentication.md\n(one authoritative copy)"]
        canonical --> vpOut["VitePress site"]
        canonical --> nxOut["Next.js site"]
    end

---

The Value Proposition

Single canonical source — no drift

There is exactly one Markdown file per documentation topic. Both documentation sites read from the same source via automatically maintained symlinks. If the canonical file says X, both sites say X. Drift is architecturally impossible.

Automated sync — zero manual synchronisation

After writing or editing a canonical file, the developer runs one command:

uv run scripts/docs-sync.py sync

This automatically updates both sites. There is no second file to remember, no copy-paste, no checklist of "update these three locations".

Git as audit trail

Every documentation change is a git commit. This provides:

• Full history of every change to every document
• Attribution (who changed what and when)
• Rollback capability (revert any change in seconds)
• Code review workflow (documentation PRs can be reviewed like code)

Two parallel rendered implementations — tooling evaluation

Both VitePress and Next.js render the exact same canonical content. The platform runs them in parallel to evaluate different documentation site technologies side by side — comparing build experience, rendering quality, plugin ecosystem, and developer ergonomics — without any additional content maintenance cost.

---

The Two Documentation Sites

flowchart LR
    canonical["Canonical .md files\ndocs/docs-site/"]

    canonical --> vp["VitePress\n(registry-docs-vitepress)\nnextjs.docs.registry.hochguertel.work"]
    canonical --> nx["Next.js\n(registry-docs-nextjs)\ndocs.registry.hochguertel.work"]

    vp --> same["Same content\nSame pages"]
    nx --> same

Both sites render the same content. The point of running them in parallel is to evaluate the tooling, not to serve different users.

VitePress — Static Site Generator

Attribute	Value
URL	docs.registry.hochguertel.work
Content scope	All documentation (every page)
Rendering model	Static build at container startup
Container	registry-docs-vitepress

VitePress builds a static site at container startup and serves it at high speed. It includes the full documentation hierarchy: all registry types, cross-cutting guides, operational references, and platform documentation.

Next.js — React Application

Attribute	Value
URL	nextjs.docs.registry.hochguertel.work
Content scope	All documentation (every page)
Rendering model	Server-side rendering on request
Container	registry-docs-nextjs

Next.js serves the same documentation as VitePress but as a React application with server-side rendering. Content is rendered on request, so page updates reflect immediately without a container restart.

---

Content Governance Model

Who owns canonical docs?

Canonical documentation files live in docs/docs-site/ in the main Registry Platform repository. Ownership follows the standard code ownership model:

• Registry-specific docs (docker/, maven/, etc.) are owned by the team responsible for that registry
• Cross-cutting guides (guides/) are owned by the platform team
• The docs-site system documentation (features/) is owned by the infrastructure team

How changes flow to both sites

sequenceDiagram
    participant Author as Content Author
    participant Git as Git Repository
    participant Sync as docs-sync.py
    participant VitePress as VitePress Container
    participant NextJS as Next.js Container

    Author->>Git: edit canonical .md + commit
    Author->>Sync: uv run docs-sync.py sync
    Sync->>Git: update .service-specific/ symlinks + commit
    Note over VitePress: On next restart:<br/>reads symlinks → builds site
    Note over NextJS: On next request:<br/>reads symlinks → serves guide

Changes take effect:

• Next.js: immediately after the symlinks are updated on the host filesystem (no container restart needed)
• VitePress: after the container is restarted (the static build runs at startup)

Git as governance

Because all documentation changes flow through git commits:

• Pull request reviews can gate documentation changes the same way code changes are reviewed
• Branch protection rules can require approval before documentation is merged
• CI checks (uv run scripts/docs-sync.py check) validate that the sync is consistent before merge

---

How to Request New Documentation

Documentation on the Registry Platform is a file, not a ticket. To request a new page:

1. Identify the canonical location — is this a guide (put in guides/), a registry-specific doc (put in docker/, maven/, etc.), or a platform doc?

2. Create the file:

   touch docs/docs-site/guides/my-new-guide.md

3. Write content (minimum: frontmatter with title and description + body).

4. Run sync and commit:

   uv run scripts/docs-sync.py sync
   git add docs/docs-site/
   git commit -m "docs: add my-new-guide"

There is no additional configuration required. VitePress automatically discovers new pages (all *.md files are included by default). Next.js automatically discovers new guides (all *.mdx files in guides/ are included).

For documentation that requires a sidebar entry in VitePress, a one-line addition to docs-site-vitepress/.vitepress/config.mts is needed. This is a developer task that takes approximately 2 minutes.

---

Quality Indicators

The primary quality indicator is the output of the check command:

uv run scripts/docs-sync.py check

Output	Meaning
✓ All symlinks are valid. (exit 0)	All documentation is in sync. Both sites can serve all content.
✗ [vitepress] … (exit 1)	At least one symlink is broken. One or both sites may be missing content or serving errors.

This command runs in under one second and is integrated into the CI pipeline. A failing check blocks deployment.

Container health provides a secondary indicator. The Homepage dashboard shows the health status of both docs containers. A container in unhealthy state means it cannot serve documentation.

Operational targets:

Metric	Target
docs-sync.py check exit code	0 (always)
VitePress container health	Healthy within 60s of start
Next.js container health	Healthy within 30s of start

---

Scalability — Adding New Docs Sites

The platform is designed to accommodate additional documentation renderers with minimal effort. Adding a new documentation site requires:

1. Adding ~10 lines to docs-sync.yml (defining which files the new service receives)
2. Running uv run scripts/docs-sync.py sync to generate the content root
3. Writing a Dockerfile and compose file for the new service
4. Configuring the new service to read from .service-specific/<new-service>/

The canonical content requires no changes when a new site is added. The existing Markdown files are immediately available to the new renderer.

Estimated time to add a new documentation site: 15–30 minutes of configuration work for a platform engineer. No content migration required.

---

Risks and Mitigations

graph TD
    subgraph risks ["Identified Risks"]
        r1["VitePress build failure\nat container start"]
        r2["Broken symlink in\n.service-specific/"]
        r3["Canonical file deleted\nwithout re-sync"]
        r4["Frontmatter missing\nfrom canonical file"]
    end

    subgraph mitigations ["Mitigations"]
        r1 --> m1["Container transitions to\n'unhealthy' → Homepage alert"]
        r2 --> m2["docs-sync.py check exits 1\nin CI — blocks deployment"]
        r3 --> m3["docs-sync.py sync removes\nstale symlinks automatically"]
        r4 --> m4["docs-sync.py injects\nauto-derived values —\nsite continues to function"]
    end

Risk	Impact	Likelihood	Mitigation
VitePress build fails at startup	VitePress site down	Low	Container health check → Homepage alert
Broken symlink not caught before deploy	Missing page on one or both sites	Very Low	CI check command exits 1 and blocks deploy
Canonical file deleted without sync	Stale symlinks in .service-specific/	Low	sync removes stale outputs; check catches broken ones
Missing frontmatter	Auto-derived values used; real file written instead of symlink	Medium	Operational, not a site outage; prompts content improvement
Two contributors edit the same file	Git merge conflict	Low	Standard git workflow — same as any code conflict

---

Summary

The docs-site platform solves the documentation drift problem by providing a single canonical source for all Registry Platform documentation. The key outcomes:

• One file to edit for any documentation change — both sites stay current automatically
• No manual synchronisation — docs-sync.py sync handles all service-specific concerns programmatically
• Git-based governance — all changes are auditable, reviewable, and reversible
• CI-validated — docs-sync.py check ensures consistency before every deploy
• Extensible — adding a new documentation site is 15–30 minutes of configuration, not a content migration project