Skip to content

Vijfpas Documentation Distribution

This document defines how teams author, consume, and publish platform documentation.

1. Source of truth

The authoritative platform documentation source is the vijfpas monorepo.

Canonical content lives under this repository's docs/ path.

The earlier split docs repository vijfpas-platform-docs is retained only as archival reference during the rollback period. Until a single replacement upstream for the monorepo is designated, treat the monorepo content itself rather than any split-repo URL as authoritative.

Rules:

  • Architecture, policy, implementation, runbooks, and ADRs are authored in the monorepo docs/ tree first.
  • Archived split repos must not be edited as the primary source of truth.
  • Team repositories must not keep their own authoritative copy of platform documentation.
  • Team repositories may keep short pointers to the canonical platform docs and local team-specific addenda.

2. Team bootstrap model

Recommended model for each team:

  1. Clone the authoritative vijfpas monorepo for platform documentation access.
  2. Clone archived split repos only when a task needs historical comparison or salvage.
  3. Clone other repos only when the task really needs local inspection or patching.

3. Team repo integration

Each team repository should contain a short pointer file such as PLATFORM_DOCS.md or a README section with:

  • canonical repo: vijfpas
  • canonical path: docs/
  • primary entry points:
  • platform.md
  • implementation.md

That keeps team repos lightweight while avoiding duplicated platform policy.

Reusable assets in this repo remain available if a team still wants a local pointer file:

  • pointer template: templates/PLATFORM_DOCS.md
  • installer helper: scripts/install-platform-docs-pointer.sh /path/to/team-repo

4. Archived split repo handling

Rules:

  • There is no authoritative mirror workflow at the moment; the monorepo is the source.
  • If a split repo must be retained, refresh it one-way from the monorepo after the monorepo change is reviewed.
  • Do not cherry-pick changes from split repos back into the monorepo unless you are doing deliberate history salvage.

Current archive list:

  • vijfpas-platform-docs
  • vijfpas-platform-infra
  • vijfpas-platform-nfr
  • vijfpas-platform-pfm
  • vijfpas-platform-shared

5. Authoring and sync workflow

Normal workflow:

  1. Change platform docs in the vijfpas monorepo.
  2. Review and merge there.
  3. If an archived split repo still needs a snapshot, publish or export from the monorepo afterward.
  4. Record any one-off salvage or archive refresh as explicit follow-up work.

6. Guardrails

  • Do not edit archived split repos first and then treat them as authoritative.
  • Do not fork policy text into team repos.
  • Keep local team docs limited to team-specific implementation details, procedures, and exceptions.
  • When a platform behavior changes, update the monorepo docs/ tree in the same change window as the implementation.

7. Published docs portal

The current published read-only documentation website is:

  • https://docs.vijfpas.com

Publishing rules:

  • the monorepo docs/ tree remains authoritative
  • the public portal is a rendered view, not an editing surface
  • the public portal publishes the curated Platform and Infrastructure tracks
  • runbooks/, adrs/, and adrlog.md remain authoritative in Git but are intentionally excluded from the public portal
  • Mermaid diagrams in published pages are rendered client-side in the portal from a vendored local JavaScript asset rather than an external CDN
  • the normal publish path is the GitLab pipeline for this repo on protected branch prd
  • feature branches and merge requests prepare docs changes; only a push or merge result on prd should publish docs.vijfpas.com
  • previous state belongs in Git history, not in separate migration docs or a mutable portal
  • if the public portal drifts or breaks, rebuild it from the monorepo rather than editing runtime content manually