Source-Backed Documentation

Summary

This thread explains how source-backed documentation can support external writing without requiring the reader to have the repo open. Public pages should be evidence-based, but not every implementation path needs to become a public reading path.

Reader Question

How can an engineering site preserve source discipline while keeping public reading paths useful?

Surface Or Workflow

The public surface is a filtered static export. It contains reviewed public pages, reviewed visuals, and public-scoped graph/search output.

Lifecycle

Internal pages cite source paths and compose into threads. Public candidates are reviewed for privacy, metadata, visuals, and source exposure. The public build exports only reviewed pages and omits full internal inventory.

Child Threads

Implementation Boundaries

This page explains the publishing mechanism and links to reviewed pages. It keeps implementation-heavy internals out of the primary reading path.

Tradeoffs

Public documentation loses some precision when source maps are not the main navigation device. The benefit is that the story remains useful without asking the reader to inspect the codebase.

Visual

The current visual is a public-reviewed graph neighborhood. The intended visual is a filter diagram from source-backed pages to reviewed public export.

Source Evidence

  • docs/public/platform-journey-strategy.md
  • docs/engineering/start/platform-map.md
  • docs/engineering/concepts/engineering-principles.md
  • docs/engineering/architecture/monorepo-as-operational-platform.md
  • docs/engineering/threads/public-platform-journey.md