dss/docs/01_core/DOCUMENTATION_GUIDE.md

DSS Documentation Guide

Version 1.0.0 | Last Updated: 2025-12-08 | Status: Production

This guide helps you find the right documentation for your task. Start here, find your scenario, and jump to the right doc.

---

I'm New to DSS

Goal: Understand what DSS is and get started

Read In This Order:

1. PRINCIPLES.md (5 min) - What DSS believes
2. README.md (5 min) - Project overview
3. QUICK_REFERENCE.md (5 min) - Key links and commands
4. This guide (you're reading it!)

Then Choose Your Path:

• Integrating DSS into your project? → INTEGRATION_GUIDE.md
• Contributing to DSS? → CONTRIBUTION_GUIDE.md
• Setting up for development? → DEVELOPMENT_SETUP.md

---

I Need to Do Something Specific

I'm Making a Structural Decision

Question: Will this affect how components, tokens, or APIs work?

Read:

• PRINCIPLES.md (understand the 5 core principles)
• BEST_PRACTICES.md (how to apply principles)
• .knowledge/adrs/ (how similar decisions were made)

Then:

• Create an ADR documenting your decision
• Open PR referencing the ADR

---

I'm Writing Code

Question: What's the contract I need to follow?

Read:

• ARCHITECTURE.md (system structure and design)
• API_CONTRACTS.md (endpoint specifications)
• BEST_PRACTICES.md (implementation patterns for your principle)

Then:

• Follow the patterns in ARCHITECTURE.md
• Respect the contracts in API_CONTRACTS.md
• Link to BEST_PRACTICES.md in your PR if needed

---

I'm Adding an API Endpoint or MCP Tool

Read:

• API_CONTRACTS.md (existing endpoints)
• BEST_PRACTICES.md § Principle 5 (tool-first architecture)
• docs/03_reference/MCP_TOOLS_SPEC.md (how to design tools)

Then:

1. Design MCP tool (primary)
2. Implement tool
3. REST endpoint wraps tool
4. Document in API_CONTRACTS.md with new version
5. Create ADR for architectural decision

---

I'm Integrating DSS into My Project

Read:

• QUICK_REFERENCE.md (overview)
• INTEGRATION_GUIDE.md (step-by-step integration)
• API_CONTRACTS.md (endpoints you'll use)
• docs/03_reference/MCP_TOOLS_SPEC.md (available tools)

Questions?

• "How do I do X?" → Search INTEGRATION_GUIDE.md
• "What endpoints are available?" → See API_CONTRACTS.md
• "How do tokens work?" → See docs/03_reference/TOKEN_SYSTEM.md

---

I'm Deploying DSS

Read:

• PROJECT_STATUS.md (current deployment status)
• DEPLOYMENT_GUIDE.md (step-by-step deployment)
• PRODUCTION_READINESS.md (checklist before deploy)
• TROUBLESHOOTING.md (when things go wrong)

Then:

• Check PRODUCTION_READINESS.md checklist
• Follow DEPLOYMENT_GUIDE.md steps
• Update PROJECT_STATUS.md after successful deploy

---

I'm Debugging Something

Read:

• PROJECT_STATUS.md (known issues section)
• TROUBLESHOOTING.md (common problems)
• ARCHITECTURE.md (understand component interactions)
• Log files in logs/ directory

Still stuck?

• Check .knowledge/adrs/ for related decisions
• Review ANTI_PATTERNS_AND_LEARNINGS.md for common mistakes
• Ask team in Slack with reference to docs you read

---

I'm Reviewing a PR

Checklist:

• Does this violate any principles? → See PRINCIPLES.md
• Did they follow best practices? → See BEST_PRACTICES.md
• Should this be documented? → Where should it go?
• Is this an architectural change? → ADR needed?
• Version numbers updated? → See BEST_PRACTICES.md § Principle 2

Look for anti-patterns: See ANTI_PATTERNS_AND_LEARNINGS.md for common mistakes

---

Documentation by Tier

Tier 1: Constitutional Documents (Immutable, Versioned)

These change only through semantic versioning. They define the system.

Document	Purpose	Read When
PRINCIPLES.md	Core values (5 principles)	Onboarding, making decisions
API_CONTRACTS.md	API endpoint specifications	Building integrations, implementing endpoints
ARCHITECTURE.md	System design, structure	Understanding system, making changes

Update Process:

1. Change file
2. Bump version (MAJOR.MINOR.PATCH)
3. Add changelog entry
4. Open PR
5. Merge and tag (git tag v1.2.0)

---

Tier 2: Current State Documents (Living, Weekly Updates)

These reflect production reality. Updated at least weekly.

Document	Purpose	Read When
PROJECT_STATUS.md	Current deployment, bugs, roadmap	Weekly reviews, planning, status checks
IMPLEMENTATION_SUMMARY.md	Feature inventory by phase	Understanding what's shipped
README.md	Project overview, quick links	First time visiting repo

Update Process:

1. Every Friday: Review and update
2. Mark "Last Updated" with current date
3. Update bugs, roadmap, deployment status
4. Commit to main branch

---

Tier 3: How-To Guides (Reference Documents)

Detailed guidance on specific tasks. Updated as needed.

Document	Purpose	Read When
QUICK_REFERENCE.md	Cheat sheet, commands, quick links	Need to find something fast
INTEGRATION_GUIDE.md	How to integrate DSS into your project	Using DSS in your own project
DEPLOYMENT_GUIDE.md	Step-by-step deployment process	Deploying to production
MIGRATION_GUIDE.md	How to upgrade between versions	Upgrading DSS version
MCP_TOOLS_SPEC.md	Available MCP tools and how to use them	Using MCP tools in automation
CONTRIBUTION_GUIDE.md	How to contribute to DSS	Contributing code changes
DEVELOPMENT_SETUP.md	Local development environment	Setting up to develop DSS
PRODUCTION_READINESS.md	Pre-deployment checklist	Before deploying to production
TROUBLESHOOTING.md	Common problems and solutions	Debugging issues

Update Process:

1. Update when procedures change
2. Mark "Last Updated" date
3. Review monthly for staleness
4. Archive if superseded by new guide

---

Tier 4: Knowledge Archive

Historical records, old versions, archived docs.

Document Type	Purpose	Read When
.knowledge/adrs/	Architecture Decision Records	Understanding why decisions were made
docs/archive/versions/	Old API/Architecture versions	Integrating with old systems
docs/archive/	Historical documents	Research, understanding evolution

---

Documentation Structure

docs/
├── 01_core/
│   ├── PRINCIPLES.md                    # Tier 1: What we believe
│   ├── BEST_PRACTICES.md               # How to apply principles
│   ├── API_CONTRACTS.md                # Tier 1: API spec
│   ├── ARCHITECTURE.md                 # Tier 1: System design
│   ├── ANTI_PATTERNS_AND_LEARNINGS.md  # What not to do
│   └── DOCUMENTATION_GUIDE.md          # This file
│
├── 02_status/
│   ├── PROJECT_STATUS.md               # Tier 2: Current state
│   ├── IMPLEMENTATION_SUMMARY.md       # Tier 2: Feature inventory
│   └── CHANGELOG.md                    # Version history
│
├── 03_reference/
│   ├── QUICK_REFERENCE.md              # Tier 3: Cheat sheet
│   ├── INTEGRATION_GUIDE.md            # Tier 3: How to integrate
│   ├── DEPLOYMENT_GUIDE.md             # Tier 3: How to deploy
│   ├── MIGRATION_GUIDE.md              # Tier 3: Version upgrades
│   ├── MCP_TOOLS_SPEC.md               # Tier 3: Tool reference
│   ├── TOKEN_SYSTEM.md                 # Tier 3: Token guide
│   ├── PRODUCTION_READINESS.md         # Tier 3: Deploy checklist
│   ├── TROUBLESHOOTING.md              # Tier 3: Common problems
│   ├── CONTRIBUTION_GUIDE.md           # Tier 3: How to contribute
│   └── DEVELOPMENT_SETUP.md            # Tier 3: Dev environment
│
├── archive/
│   ├── versions/
│   │   ├── v1.0.0/
│   │   │   ├── API_CONTRACTS.md
│   │   │   └── ARCHITECTURE.md
│   │   └── v1.1.0/
│   │       └── ...
│   ├── phases/
│   └── 2024/
│
└── README.md                           # Repo overview

---

How to Find Information

By Task

I Want To...	Start Here
Understand DSS	PRINCIPLES.md
Integrate DSS	INTEGRATION_GUIDE.md
Deploy DSS	DEPLOYMENT_GUIDE.md
Contribute code	CONTRIBUTION_GUIDE.md
Write an endpoint	API_CONTRACTS.md + BEST_PRACTICES.md
Use MCP tools	MCP_TOOLS_SPEC.md
Debug something	TROUBLESHOOTING.md
Check status	PROJECT_STATUS.md
Upgrade version	MIGRATION_GUIDE.md
Understand a decision	.knowledge/adrs/

By Role

I'm A...	Read These
New Developer	PRINCIPLES.md → README.md → QUICK_REFERENCE.md
Product Manager	PROJECT_STATUS.md → IMPLEMENTATION_SUMMARY.md
DevOps Engineer	DEPLOYMENT_GUIDE.md → PRODUCTION_READINESS.md
API Consumer	API_CONTRACTS.md + INTEGRATION_GUIDE.md
System Architect	ARCHITECTURE.md + ANTI_PATTERNS_AND_LEARNINGS.md
PR Reviewer	PRINCIPLES.md + BEST_PRACTICES.md

By Principle

Principle	Learn More In
Design is Architectural	PRINCIPLES.md § 1, ARCHITECTURE.md
Contracts are Immutable	BEST_PRACTICES.md § Principle 2, API_CONTRACTS.md
Single Source of Truth	BEST_PRACTICES.md § Principle 3, ANTI_PATTERNS_AND_LEARNINGS.md
Decisions Traceable	BEST_PRACTICES.md § Principle 4, .knowledge/adrs/
Operations as Tools	BEST_PRACTICES.md § Principle 5, MCP_TOOLS_SPEC.md

---

Reading Paths

Path 1: Onboarding (30 minutes)

1. PRINCIPLES.md (5 min)
   ↓
2. README.md (5 min)
   ↓
3. QUICK_REFERENCE.md (5 min)
   ↓
4. Start with relevant Tier 3 guide for your task (15 min)

Path 2: Making a Decision (45 minutes)

1. PRINCIPLES.md (5 min)
   ↓
2. BEST_PRACTICES.md for relevant principle (15 min)
   ↓
3. .knowledge/adrs/ - similar decisions (15 min)
   ↓
4. ANTI_PATTERNS_AND_LEARNINGS.md (10 min)
   ↓
5. Create ADR for your decision

Path 3: Architectural Change (1 hour)

1. ARCHITECTURE.md (20 min)
   ↓
2. BEST_PRACTICES.md (15 min)
   ↓
3. ANTI_PATTERNS_AND_LEARNINGS.md (10 min)
   ↓
4. .knowledge/adrs/ for similar decisions (15 min)
   ↓
5. Design change, create ADR, open PR

Path 4: Integration (2 hours)

1. INTEGRATION_GUIDE.md (30 min)
   ↓
2. API_CONTRACTS.md (30 min)
   ↓
3. QUICK_REFERENCE.md (10 min)
   ↓
4. Implement integration, reference docs
   ↓
5. TROUBLESHOOTING.md if issues (20 min)

---

Docs That Reference Each Other

Single Source of Truth Flow:

PRINCIPLES.md (what we believe)
    ↓
BEST_PRACTICES.md (how to implement)
    ↓
API_CONTRACTS.md, ARCHITECTURE.md (actual specs)
    ↓
IMPLEMENTATION_GUIDE.md, DEPLOYMENT_GUIDE.md (how-to guides)
    ↓
Actual code implementation

Decision Flow:

BEST_PRACTICES.md (decision criteria)
    ↓
.knowledge/adrs/ (record decision)
    ↓
PR links to ADR (traceability)
    ↓
Code implements decision
    ↓
ARCHITECTURE.md or API_CONTRACTS.md (documents result)

---

Keeping Docs Current

Weekly (Every Friday)

• Update PROJECT_STATUS.md
  • Mark "Last Updated"
  • Update bugs list
  • Update roadmap
  • Update deployment status

Monthly (First Friday)

• Audit all Tier 3 docs for staleness
  • Any docs older than 30 days?
  • Still accurate?
  • Update or archive?

Per Release

• Update API_CONTRACTS.md version
• Add CHANGELOG entry
• Update MIGRATION_GUIDE.md if breaking changes
• Update IMPLEMENTATION_SUMMARY.md with new features
• Create tag (git tag vX.Y.Z)

When Making Major Changes

• Create or update ADR
• Update relevant Tier 1 docs
• Link PR to ADR
• Update related Tier 3 guides

---

FAQ: Finding Documentation

Q: Where are API endpoints documented? A: API_CONTRACTS.md (Tier 1, immutable)

Q: Why did we choose this architecture? A: Check ARCHITECTURE.md or .knowledge/adrs/ (decision records)

Q: What's currently deployed? A: PROJECT_STATUS.md (Tier 2, updated weekly)

Q: How do I integrate DSS? A: INTEGRATION_GUIDE.md (Tier 3, reference guide)

Q: How do I deploy changes? A: DEPLOYMENT_GUIDE.md (Tier 3, step-by-step)

Q: What's the status of feature X? A: IMPLEMENTATION_SUMMARY.md or PROJECT_STATUS.md

Q: What changed between versions? A: CHANGELOG.md or MIGRATION_GUIDE.md

Q: Is this documented? A: Yes! (probably) → Use this guide to find it

---

Last Updated: 2025-12-08 Version: 1.0.0 (new navigation guide) Status: PRODUCTION