Single Source of Truth (SSOT) Principle¶

Core Idea: One canonical place for all documentation—no scattered chaos.

The Problem: Documentation Fragmentation¶

In most organizations, documentation lives everywhere:

• 📧 Project details buried in email threads
• 💬 Decisions lost in Slack conversations
• 📄 Specs scattered across Google Docs
• 📝 Notes in personal OneNote/Evernote
• 🗂️ Old wikis that nobody updates
• 💾 Presentations on someone's laptop

Result: Nobody knows what's current. Teams waste hours searching. Decisions get revisited. Audits fail.

Our Solution: Single Source of Truth¶

All MachineAvatars documentation lives in ONE place:

machineagents-docs/

That's it. No exceptions.

What Lives Here¶

✅ YES - Belongs in Docs Repo¶

❌ NO - Does NOT Belong in Docs Repo¶

How SSOT Works in Practice¶

Scenario 1: New Architecture Decision¶

flowchart LR
    A[Decision Needed] -->|Discussion| B[Slack/Meeting]
    B -->|Consensus| C[Create ADR]
    C -->|Write| D[machineagents-docs/11-architecture-decision-records/]
    D -->|PR Review| E[Merged]
    E -->|Deployed| F[Single Source of Truth]

    B -.->|No decision yet| G[Stays in Slack]

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

Key Point: Discussions happen in Slack, but decisions live in docs.

Scenario 2: API Changes¶

❌ Wrong Way:

Developer: Updates code
↓
Posts in Slack: "Hey, I changed the /login endpoint"
↓
Someone might update docs... eventually... maybe?

✅ Right Way:

Developer: Updates code
↓
Updates: docs/6-technical-specification/api-documentation/auth.md
↓
Updates: OpenAPI spec
↓
PR includes: Code + Documentation
↓
Both merge together
↓
Documentation always matches reality

Scenario 3: Onboarding New Developer¶

Without SSOT:

New Dev: "How do I set up the environment?"
↓
Asks 5 different people
↓
Gets 5 different answers (some outdated)
↓
Spends 2 days figuring it out

With SSOT:

New Dev: Opens machineagents-docs
↓
Follows docs/getting-started.md
↓
Environment running in 2 hours
↓
If docs are wrong → Opens PR to fix them
↓
Next person benefits

Enforcing SSOT¶

Policy: No Shadow Documentation¶

If it's not in machineagents-docs, it doesn't exist.

• Want to document a design decision? → Create an ADR
• Found outdated info? → Update the docs, don't just complain
• Slack discussion reached conclusion? → Document it in relevant section

Git as Guardian¶

All documentation changes go through:

1. Branch creation
2. Content update
3. Peer review
4. Approval
5. Merge to main
6. Auto-deployment

This ensures:

• ✅ All changes are tracked
• ✅ Nothing changes without review
• ✅ History is preserved
• ✅ Conflicts are resolved

Version Control = Time Travel¶

Because docs are in Git, we can:

See history:

git log docs/3-product-architecture/system-overview.md

Compare versions:

git diff v1.0...v2.0 -- docs/

Blame (who changed what):

git blame docs/mkdocs.yml

Restore old version:

git checkout abc1234 -- docs/api-documentation/

This is impossible with Google Docs!

Benefits of SSOT¶

For Teams¶

For Audits¶

For Investors¶

Common Objections & Responses¶

"Markdown is too technical for non-engineers"¶

Response: That's why we have layered readability. Business folks read the rendered website, not raw Markdown.

URL: https://docs.machineagents.ai looks professional, not technical.

"What about collaborative editing? Google Docs is easier."¶

Response:

• For final docs → Git (single source of truth)
• For drafting → Google Docs is fine as a temporary workspace
• But once approved → migrate to machineagents-docs

"I don't want to learn Git just to update docs"¶

Response: You don't need to! Options:

1. Edit directly on GitHub web interface (no Git commands)
2. Use VS Code with Git extensions (visual)
3. Ask the docs team to update for you

"What if the repo is down?"¶

Response:

• Docs are deployed to a static site (stays up even if Git is down)
• GitHub has 99.9% uptime (better than Google Docs)
• We have local clones on every developer machine

Migration from Scattered Docs¶

Step 1: Audit Current State¶

Find all existing documentation:

• Search Google Drive
• Search Confluence/Notion
• Search shared folders
• Review Slack pinned messages
• Ask team members

Step 2: Prioritize¶

Step 3: Migrate¶

For each document:

1. Convert to Markdown (use Pandoc if needed)
2. Place in correct section
3. Add frontmatter (owner, date, version)
4. PR and review
5. Archive old copy with pointer to new location

Step 4: Communicate¶

Announce to team:

• "All docs now live in machineagents-docs"
• Share link to deployed site
• Set up Slack command: /docs <query> (future)
• Update bookmarks

Rule of Thumb¶

Before creating any documentation, ask:

"Is there already a place for this in machineagents-docs?"

If yes → Add it there
If no → Maybe create a new section, or it doesn't need documenting

Real-World Example: API Documentation¶

Before SSOT (chaos):

- Swagger JSON somewhere on a server
- README in backend repo (outdated)
- Postman collection (someone's local machine)
- Wiki page (abandoned 6 months ago)
- Developer's personal notes

After SSOT (organized):

machineagents-docs/
  docs/
    6-technical-specification/
      api-documentation/
        index.md           ← Overview
        openapi.yaml       ← Full spec
        auth-service.md    ← Per-service docs
        payment-service.md
        errors.md          ← Error codes

One truth. One place. Always current.

Maintenance¶

Weekly¶

• Check for broken links
• Update "Last Modified" dates
• Merge pending PRs

Monthly¶

• Review stale docs (> 3 months old)
• Archive deprecated content
• Update metrics in dashboards

Quarterly¶

• Full audit of completeness
• Team survey on documentation quality
• Reorganize if needed

Success Metrics¶

We measure SSOT effectiveness:

Related Principles¶

• Layered Readability - SSOT doesn't mean one big document
• Versioned & Traceable - Git enables SSOT
• Audit-Ready - SSOT makes audits possible

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

"One place. One truth. Everyone aligned."