Versioning & Trace ability Principle¶

Core Idea: Every documentation change links to a product decision.

The Problem: Orphaned Documentation¶

Most documentation fails because it's disconnected from the product:

📄 Docs say Feature X works one way
💻 Code implements it differently
❓ Nobody knows which is right
🤷 No record of why it changed

Result: Trust in documentation erodes. People stop reading it.

Our Solution: Traceable Changes¶

Every documentation change must answer:

What changed? (The diff)
Why did it change? (The reason)
When did it change? (The date)
Who changed it? (The author)
What triggered it? (Feature, bug, decision)

This creates an audit trail from idea → decision → implementation → documentation.

Traceability Matrix¶

Documentation Change	Must Link To	Example
Architecture update	Architecture Decision Record (ADR)	ADR-003: Vector DB selection
New feature	PRD + Feature Doc	3D Avatar Emotions feature
API change	API Changelog + Migration Guide	v2.0 Breaking Changes
Security update	Security Review + Incident	SSL cert rotation procedure
Process change	PDLC Update + Team Announcement	New code review process
Infrastructure	Infrastructure Change Request	Migration to Azure

No orphaned changes. Every edit has a parent.

Version Control with Git¶

Why Git for Documentation?¶

Git provides automatic traceability:

# See all changes to a file
git log docs/3-product-architecture/system-overview.md

# See who wrote each line (blame)
git blame docs/api-documentation/auth.md

# See what changed in a specific commit
git show abc1234

# Compare two versions
git diff v1.0...v2.0 -- docs/

# Find when a line was introduced
git log -S "MongoDB" -- docs/

Impossible with Google Docs!

Document Versioning Standard¶

Semantic Versioning for Docs¶

We use Major.Minor versioning:

**Version:** 2.3  
**Last Updated:** 2025-12-26

Rules:

Change Type	Version Update	Example
Major restructure	X.0	1.0 → 2.0
New section added	0.X	2.3 → 2.4
Content update	0.X	2.3 → 2.4
Typo fix	(no change)	Still 2.3
Link fix	(no change)	Still 2.3

Document Header Template¶

Every document MUST have:

# Document Title

> **Purpose:** What this achieves  
> **Audience:** Who should read this  
> **Owner:** Who maintains it  
> **Last Updated:** YYYY-MM-DD  
> **Version:** Major.Minor  
> **Status:** Draft | Active | Deprecated

Example:

# AI/ML Architecture

> **Purpose:** Document AI model selection, RAG implementation, and evaluation  
> **Audience:** ML Engineers, Technical Auditors, Investors  
> **Owner:** ML Engineering Lead  
> **Last Updated:** 2025-12-26  
> **Version:** 1.3  
> **Status:** Active

Linking Documentation to Product¶

Pattern 1: Feature Documentation¶

When adding a feature:

PRD written (features/3d-avatar-emotions-prd.md)
Design approved
Code implemented (PR #234)
Feature doc created (docs/12-features-capabilities/3d-avatar-emotions.md)

Feature doc includes:

# 3D Avatar Emotions

## Product Context

- **PRD:** [Avatar Emotions Product Requirements](../../features/3d-avatar-emotions-prd.md)
- **Implemented:** Q4 2024 (v2.3.0)
- **Related PR:** [#234](https://github.com/askgalore/machineagents-fe/pull/234)
- **Owner:** Frontend Team

## What It Does

[... feature description ...]

##Why We Built It
[... from PRD ...]

## Technical Implementation

[... links to code, architecture ...]

Pattern 2: Architecture Decision Records (ADRs)¶

When making an architectural decision:

Decision needed (e.g., choose vector database)
ADR created (docs/11-architecture-decision-records/adr-003-milvus.md)
Decision approved
Implementation (code changes)
Architecture docs updated (link to ADR)

Architecture doc references ADR:

# Data Architecture

## Vector Database: Milvus

We use Milvus for storing and querying vector embeddings.

**Why Milvus?** See [ADR-003: Vector Database Selection](../13-architecture-decision-records/adr-003-milvus.md)

**Benchmarks:**

- Query latency: 15ms p95 (vs. 450ms for Postgres pgvector)
- Cost: $200/month (vs. $2K/month for Pinecone)

**Decision Date:** 2024-06-01  
**Status:** Active

Pattern 3: API Changelog¶

When changing an API:

API change proposed (e.g., deprecate /v1/login)
Breaking Change Document created
Migration guide written
Changelog updated
API docs updated
Version bumped (v1 → v2)

API Changelog:

# API Changelog

## v2.0.0 (2025-01-15) - BREAKING CHANGES

### Deprecated: `/v1/login`

**Reason:** Replaced with OAuth 2.0 flow for better security

**Migration:**

```diff
# Old (v1)
- POST /v1/login
- Body: {"email": "...", "password": "..."}

# New (v2)
+ POST /v2/auth/token
+ Body: {"grant_type": "password", "username": "...", "password": "..."}
```

Timeline:

v1 deprecated: 2025-01-15
v1 sunset: 2025-07-15 (6 months)

Decision documented in Architecture Decision Records

---

## Git Commit Message Standards

Our commits link documentation to changes:

### Format

type(scope): subject

body

footer

### Types

| Type | Use Case | Example |
|------|----------|---------|
| `feat` | New feature doc | `feat(docs): add 3D avatar emotions guide` |
| `docs` | Documentation update | `docs(api): update rate limits` |
| `fix` | Fix incorrect info | `fix(arch): correct MongoDB version` |
| `refactor` | Reorganize docs | `refactor(docs): restructure navigation` |
| `chore` | Maintenance | `chore(docs): update dependencies` |

### Example

feat(docs): document AI bias mitigation strategy

Add comprehensive AI ethics guidelines
Document bias testing procedures
Link to model evaluation metrics

Related: ADR-015 (AI Safety) Addresses: Audit requirement #23

---

## Traceability in Practice

### Scenario: New LLM Model

```mermaid
flowchart TB
    A[Business Need: Better AI responses] --> B[PRD: Upgrade to GPT-4]
    B --> C[ADR-001: LLM Selection]
    C --> D[Benchmarking & Evaluation]
    D --> E[Decision: Adopt GPT-4]
    E --> F[Code Changes: Update LLM service]
    F --> G[Docs Update: AI/ML Architecture]
    G --> H[Docs Update: Cost Drivers]
    F --> I[API Changelog: Model parameter changes]

    C -.Links to.-> G
    C -.Links to.-> H
    F -.PR reference.-> G

    style E fill:#4CAF50,stroke:#2E7D32,color:#fff

Result: You can trace from "why better AI?" all the way to "which code changed".

Scenario: Security Incident¶

1. Incident: Unauthorized access attempt detected
   ↓
2. Post-Mortem: docs/incidents/2024-12-security-incident.md
   ↓
3. Security Update: Enhanced rate limiting
   ↓
4. Code Changes: PR #456
   ↓
5. Docs Updates:
   - docs/5-security-architecture/rate-limiting.md (updated)
   - docs/5-security-architecture/incident-response. md (updated)
   - docs/8-pdlc/security-review-process.md (new procedure)
   ↓
6. All docs link back to post-mortem

Traceability: From incident → lessons → changes → documentation.

Change Log Management¶

Global Changelog¶

docs/14-appendices/changelog.md:

# MachineAvatars Documentation Changelog

All notable changes to this documentation project.

## [2.0.0] - 2025-01-15

### Added

- AI Ethics Guidelines section
- IP Ownership documentation
- 5 new ADRs (ADR-011 through ADR-015)

### Changed

- Restructured AI/ML Architecture (now section 3.5)
- Updated pricing strategy (new Enterprise tier)

### Deprecated

- Old API versioning strategy (superseded by ADR-014)

### Removed

- Legacy webhook documentation (feature sunset)

### Fixed

- Corrected MongoDB version (4.4 → 5.0)
- Updated broken links in navigation

**Related PRs:** #123, #125, #127  
**Migration:** See [v2 Migration Guide](migrations/v1-to-v2.md)

Per-Document Changelog¶

At bottom of each major document:

---

## Document Change Log

| Version | Date       | Changes                       | Author  |
| ------- | ---------- | ----------------------------- | ------- |
| 1.3     | 2025-12-26 | Added bias mitigation section | ML Lead |
| 1.2     | 2025-11-15 | Updated model benchmarks      | ML Lead |
| 1.1     | 2025-10-01 | Added RAG architecture        | ML Lead |
| 1.0     | 2025-06-01 | Initial version               | CTO     |

Review & Update Triggers¶

Automatic Triggers¶

Documentation MUST be updated when:

Scheduled Reviews¶

Document Type	Review Frequency
Executive Summary	Quarterly
Architecture	Per major release
AI/ML	Per model update
Security	Quarterly + incident-triggered
API Docs	Per API version
User Guides	Per feature release

Audit Trail Benefits¶

For Technical Audits¶

Auditor: "Why did you choose MongoDB over PostgreSQL?"

You: "We benchmarked both. MongoDB was 40% cheaper and 2x faster for our schema-less use case. Full analysis documented in our architecture decision records."

For Investor Due Diligence¶

Investor: "How has your architecture evolved?"

You: "We maintain a comprehensive changelog showing all major changes, each linked to business decisions or technical improvements."

For New Engineers¶

New Dev: "Why is the code structured this way?"

You: "Read ADR-004: Microservices Architecture. It explains the decision, alternatives we considered, and trade-offs."

Versioning Best Practices¶

Do's ✅¶

Update version number with meaningful changes
Always update "Last Updated" date
Link to related PRs, ADRs, incidents
Keep changelogs updated
Review stale docs (> 3 months old)

Don'ts ❌¶

Don't version typo fixes
Don't skip version increments (1.2 → 1.4)
Don't forget to update parent documents
Don't break links when renaming files
Don't remove history (deprecate instead)

Tools & Automation¶

Git Hooks¶

Pre-commit hook to enforce frontmatter:

# check_frontmatter.py
import re

def validate_frontmatter(file_content):
    required = ["Purpose", "Audience", "Owner", "Last Updated", "Version"]
    for field in required:
        if field not in file_content:
            return False, f"Missing: {field}"
    return True, "OK"

Automated Changelog¶

Script to generate changelog from Git commits:

git log --oneline --decorate docs/ | grep "docs:" > CHANGELOG.md

Link Checker¶

Weekly cron job:

mkdocs build --strict  # Fails on broken links

Success Metrics¶

Metric	Target	How to Measure
All docs have version	100%	Automated check
Docs updated with releases	100%	Release checklist
Broken links	0	Weekly link check
Stale docs (>3 months)	< 10%	Git log analysis
ADRs for decisions	100%	Review process

SSOT - Versioning works because docs are in one place
Audit-Ready - Traceability enables audits
Layered Readability - All layers version together

Last Updated: 2025-12-26
Version: 1.0
Owner: Documentation Lead

"Every change tells a story."