Skip to content

docs: Create SSOT documentation registry per project #563

Description

@kcenon

What

Create a Single Source of Truth (SSOT) documentation registry in each project's
docs/README.md, listing every document with its authoritative topic, status,
and location.

Why

With 54-85 documentation files per project, there is no central index showing
which document is the authoritative source for each topic. This leads to
duplicated or conflicting information across files. An SSOT registry provides a
machine-readable, human-navigable index that prevents documentation drift.

Where

Repository File Action
common_system docs/README.md Add SSOT registry
thread_system docs/README.md Add SSOT registry
logger_system docs/README.md Add SSOT registry
container_system docs/README.md Add SSOT registry
monitoring_system docs/README.md Add SSOT registry
database_system docs/README.md Add SSOT registry
network_system docs/README.md Add SSOT registry
pacs_system docs/README.md Add SSOT registry

How

Registry Format

Each docs/README.md should contain:

# Documentation Registry

> **SSOT**: This file is the single source of truth for the documentation index
> of {project_name}.

## Document Index

| # | doc_id | Topic | Authority Document | Section | Status |
|---|--------|-------|-------------------|---------|--------|
| 1 | THR-ARCH-001 | Thread Pool Architecture | [ARCHITECTURE.md](./ARCHITECTURE.md) | §2 | Released |
| 2 | THR-GUID-001 | Queue Selection Criteria | [QUEUE_SELECTION_GUIDE.md](./QUEUE_SELECTION_GUIDE.md) || Released |
| 3 | THR-PERF-001 | Performance Baselines | [BENCHMARKS.md](./BENCHMARKS.md) | §3 | Released |

SSOT Declaration Convention

Each authoritative document should include a declaration near its top:

> **SSOT**: This section is the single source of truth for {topic}.

Implementation Steps

  1. Inventory all docs/ files per project (use existing frontmatter doc_ids from docs: Add YAML frontmatter to all docs/ markdown files #562)
  2. Determine the authoritative topic for each document
  3. Build the registry table in docs/README.md
  4. Add SSOT declarations to each authoritative document
  5. Verify no topic has multiple conflicting authority documents

Acceptance Criteria

  • All 8 projects have an SSOT registry table in docs/README.md
  • Each entry has doc_id, topic, file link, and status
  • No duplicate authority topics within a project
  • Key documents have SSOT declarations
  • All file links are valid (no broken links)

Related

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions