Documentation as Source Code for AI

options: type: guide version: “1.0.1” birth: “2026-02-16” token_size: 1123¶

Documentation as Source Code for AI¶

The Problem¶

In the era of AI-backed development, AI systems — RAG pipelines, coding agents, AI assistants — consume documentation as their primary input. They don’t read your codebase first; they read your docs. Traditional documentation practices fail in this context:

• Stale content → hallucinations: outdated docs produce confidently wrong AI outputs.

• Unstructured metadata → blind retrieval: without machine-readable frontmatter, RAG pipelines can’t filter by date, status, or scope.

• No lifecycle → noise accumulation: superseded articles left in place pollute retrieval results indefinitely.

• Flat collections → untraceable references: pre-AI knowledge bases are article dumps with no enforced structure, no dependency graph, and no automated verification.

Poor documentation is no longer just an inconvenience for humans. It is a bug in the AI system.

The Principle¶

All content in this repository is treated as production source code — versioned, tested, lifecycle-managed, and machine-readable — because it is the primary input for AI systems.

This is not a metaphor. The same engineering rigor applied to production code — diffing, testing, code review, CI/CD, garbage collection of dead code — applies to every document, ADR, and notebook in this repository.

Sean Grove (OpenAI, “The New Code”) articulates the underlying insight: “code is a lossy projection from the specification” — discarding specifications while keeping generated code is like shredding the source and version-controlling the binary. In an AI-consumed repository, documentation IS the source that AI systems compile into outputs.

How This Repository Implements the Principle¶

Each aspect of the Documentation-as-Code paradigm is governed by a concrete ADR:

The Structural Analogy¶

In source code, architecture determines where modules live, how they reference each other, and what contracts they expose. The same applies to documentation:

• Placement is semantic: a document’s directory location defines its layer, scope, and discoverability — not a flat “articles” collection.

• References are traceable: ADR cross-references, frontmatter tags, and status fields create a dependency graph analogous to import statements.

• Restructuring requires governance: moving or splitting content is a refactoring operation that demands an ADR (e.g., ADR-26026 for research extraction, ADR-26020 for hub-spoke separation) — not a casual drag-and-drop.

• Verification is automated: broken-link checks, sync-guard, and metadata validation catch structural regressions the same way unit tests catch code regressions.

This stands in direct opposition to pre-AI knowledge bases — collections of articles with no enforced structure, no traceability between documents, and no automated verification. Those collections were adequate when only humans consumed them. They are inadequate when AI systems depend on them.

Role of This Document¶

This manifesto is not an ADR. ADRs are decisions — reversible, with alternatives considered, subject to promotion gates. This document is a declaration of principles — the unchanging foundation that individual ADRs implement. It answers “why does this repository exist?” while ADRs answer “how do we build it?”

References¶

• Sean Grove, “The New Code” (OpenAI) — https://www.youtube.com/watch?v=8rABwKRsec4

• ADR Index — the full set of architectural decisions implementing these principles