Skip to main content

Docs Platform Truth

Use this page when you need the exact contract-level model for how Helpifyr public docs are structured, validated, redirected, indexed, and published.

When to use this page​

  • You need to understand the docs-system contract rather than a product or journey page.
  • You are verifying docs readiness, redirect behavior, search truth, or reviewed-publication posture.
  • You need to explain what the docs platform guarantees and what it does not guarantee.

Prerequisites​

  • You understand the owner split between source repos, jhf-docs reviewed materialization, and jhf-web live publication.
  • You can read the docs route family and generated artifact metadata.

Docs-platform model​

The docs platform is Fabric-owned shared truth for:

  • public information architecture
  • route and redirect expectations
  • search and catalog publication
  • rollout readiness and quality gates
  • the reviewed-publication contract that downstream docs workspaces and live publication consume

Architecture / Flow​

Step-by-step procedure​

1. Start with the machine-readable docs-platform routes​

Illustrative reads:

GET /api/v1/docs/platform
GET /api/v1/docs/catalog
GET /api/v1/docs/readiness
GET /api/v1/docs/redirect-map
GET /api/v1/docs/search-index

These routes answer different questions:

  • platform
    • current docs-system contract and posture
  • catalog
    • what public docs families are present
  • readiness
    • whether publication is in a healthy state
  • redirect-map
    • canonical path expectations
  • search-index
    • machine-readable search and discovery truth

2. Read the reviewed artifact metadata​

In jhf-docs, high-value evidence includes:

  • docs-site/generated/validation_report.json
  • docs-site/generated/source_revisions.json
  • docs-site/static/generated/docs-platform.json
  • docs-site/static/generated/redirect-map.json
  • docs-site/static/generated/search-index.json

These files show what the reviewed artifact believes it is publishing.

3. Keep contract truth and local overrides distinct​

The docs platform defines the shared publication contract. The jhf-docs override lane may add public-safe longform pages, but it must not silently contradict the Fabric-owned docs-platform truth.

4. Use docs-platform truth when pages look stale or inconsistent​

If a live page disagrees with local reviewed truth, use the docs-platform routes and generated metadata before guessing whether the problem is source, materialization, or publication.

Current posture​

  • language model:
    • english-first-v1
  • frontend:
    • docusaurus
  • versioning model:
    • latest-stable-versioned-release-paths
  • locale posture:
    • English-first live baseline with compatibility-only DE/FR routes until the localization wave lands

Verification​

Docs-platform truth is being applied correctly when:

  1. the right docs route family is used for the question
  2. reviewed artifact metadata is checked before publication claims are made
  3. shared contract truth and repo-owned overrides remain consistent

Common failure modes​

Treating the live page as the only docs-system evidence​

Problem:

  • source, reviewed-artifact, and publication issues get mixed together.

Better path:

  • compare docs-platform routes, generated metadata, and live output in order

Letting local overrides replace contract truth silently​

Problem:

  • the docs bundle becomes readable but no longer owner-clear.

Better path:

  • keep overrides additive and public-safe, with Fabric contract truth still explicit

Source Truth​

Next paths​