G2: Version-Controlled Documentation
Keeping documentation in the same version control repository as source code is a core practice of documentation as code. Git tracks who changed what and why for every change. Markdown's plain text format makes diffs readable and easy to review.
Documents in Confluence, Google Docs, or Word lack version history, cannot be branched or merged, and are difficult to correlate with code changes. Binary formats also make it hard for AI agents to parse content.
Principle
- All specifications MUST be written in Markdown, managed under version control (Git), and include frontmatter metadata for programmatic access.
Plain text format enables readable diffs and AI parsing. Git tracks who changed what and why, and enables branching and merging. Frontmatter fields like title, description, status, owner, created, and updated allow AI agents to parse metadata without reading full content.