Skip to content

Documentation Header Spec

Documentation Metadata Header Specification

Status: Canonical Reference
Scope: All documentation files
Last Updated: December 20, 2025 16:20:36
Created: December 20, 2025 16:00:43

Purpose

This metadata header defines the authoritative status, applicability scope, and lifecycle timestamps of a documentation file. It is used to clarify whether a document is canonical or informational, what it governs, and when it was created or last updated.

All documentation files must include this header immediately after the document title, unless explicitly stated otherwise.

Required Fields

Each documentation file MUST include the following fields, in the exact order shown below:

> **Status**: <status value>  
> **Scope**: <scope description>  
> **Last Updated**: <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-datetime" title="December 20, 2025 16:20:36 CST">December 20, 2025 16:20:36</span>  
> **Created**: <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-datetime" title="December 20, 2025 16:00:43 CST">December 20, 2025 16:00:43</span>

Field Definitions

Status

Indicates the authority level of the document.

Allowed values:

  • Canonical Reference The single source of truth. Other documents must follow this specification.

Use when: - The document defines a complete specification or contract for a system or component - The document is the authoritative reference that other documents must follow - The document defines file formats, data structures, or API contracts - Examples: solution-contract.md, generator-contract.md, ontology-design.md

  • Normative Defines rules or constraints that must be followed.

Use when: - The document defines specific rules, guidelines, or constraints that must be followed - The document establishes standards for documentation, linking, or processes - The document is not a complete specification but contains binding rules - Examples: MKDOCS_CONTENT_GUIDE.md (defines linking rules)

  • Informational Provides explanation or background; not strictly binding.

Use when: - The document provides guides, tutorials, or explanations - The document describes historical context or migration processes - The document is helpful but not required to follow - Examples: architecture-migration.md, github-pages-setup.md, act-local-github-actions.md

  • Draft Work in progress; subject to change.

Use when: - The document is actively being developed - The content is not yet finalized - The document may change significantly

Each document MUST have exactly one status value.

Distinguishing Canonical Reference from Normative: - Canonical Reference: Complete specification/contract (e.g., file format, data structure, API contract) - Normative: Rules and constraints (e.g., documentation standards, linking guidelines, process rules)

Scope

Defines what files, directories, or components this document applies to.

Guidelines:

  • Be explicit and unambiguous
  • Prefer directory-based scopes when possible
  • Use inline code formatting for paths

Examples:

  • All generator files in generators/
  • All solution files in solutions/
  • Documentation under docs/architecture/
  • Repository-wide

Last Updated

<span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-datetime" title="December 20, 2025 16:20:36 CST">December 20, 2025 16:20:36</span>
  • Automatically populated by the documentation build system
  • Reflects the last Git commit that modified the file
  • MUST NOT be manually edited

Created

<span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-datetime" title="December 20, 2025 16:00:43 CST">December 20, 2025 16:00:43</span>
  • Automatically populated by the documentation build system
  • Reflects the initial Git commit that introduced the file
  • MUST NOT be manually edited

Canonical Examples

Generator Specification Documents

# Generator Contract Specification

> **Status**: Canonical Reference  
> **Scope**: All generator files in `generators/`  
> **Last Updated**: <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-datetime" title="December 20, 2025 16:20:36 CST">December 20, 2025 16:20:36</span>  
> **Created**: <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-datetime" title="December 20, 2025 16:00:43 CST">December 20, 2025 16:00:43</span>

This document defines the **contract** for test case generator files...

Solution Specification Documents

# Solution Contract Specification

> **Status**: Canonical Reference  
> **Scope**: All solution files in `solutions/`  
> **Last Updated**: <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-datetime" title="December 20, 2025 16:20:36 CST">December 20, 2025 16:20:36</span>  
> **Created**: <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-datetime" title="December 20, 2025 16:00:43 CST">December 20, 2025 16:00:43</span>

This document defines the **contract** for solution files...

Placement Rules

  • The metadata header MUST appear immediately after the document title (the first # heading)
  • The structure MUST follow this order:
  • Document title (first # heading)
  • Blank line
  • Metadata header block
  • Blank line
  • Document body content
  • A blank line MUST follow the header block before body text begins

Rationale (Optional Section)

This header standard exists to:

  • Clearly distinguish canonical specifications from explanatory notes
  • Define enforcement boundaries for generators, solutions, and tooling
  • Enable automated auditing and documentation freshness checks
  • Improve long-term maintainability in large repositories