Skip to main content
INFORMATIVEACTIVEDocumentation Governance
Truth Source: Repository schemas and tests are authoritative.

Docs Author Rules

1. Before You Write​

Before creating or modifying documentation:

  • Confirm the content fits an existing section (see Sidebar Organization)
  • Verify no duplicate content exists
  • Identify the normative weight (Normative, Informative, Mixed)
  • Check if this affects the Alignment Index

2. When You Must Update the Alignment Index​

Update REPO_DOCS_CODE_ALIGNMENT.md when:

  • A new schema is added
  • A new package is published
  • A new Golden Flow is defined
  • Documentation claims change regarding code location

3. Frontmatter Requirements​

All documentation files MUST include:

---
sidebar_position: <number>
doc_type: reference | guide | specification
status: active | draft | deprecated
authority: <governance authority>
description: "<brief description>"
title: <page title>
---

4. Sidebar Organization Rules​

CategoryContent TypeMay Contain
ReferenceOverview, GlossaryNon-normative
ArchitectureL1–L4 specsNormative
ModulesModule specsNormative
Golden FlowsValidation scenariosNormative
GovernancePolicies, statementsMixed
StandardsExternal mappingsInformative
SDK / RuntimeImplementation docsReference
Compliance / Enterprise / AdoptionGuidanceInformative

Do not mix normative and informative content in the same page.

5. Writing Style Guidelines​

  • Use clear, concise language
  • Define acronyms on first use
  • Link to source schemas when referencing protocol entities
  • Use admonitions (> [!NOTE], > [!IMPORTANT]) for callouts
  • Maintain consistent heading hierarchy (H1 for title, H2 for sections)

6. Review Checklist (Before Merge)​

  • Content fits existing section
  • No new protocol claims
  • No new external standard claims
  • Alignment Index updated (if applicable)
  • Links work
  • Build passes

Documentation Governance 2025-12-21