# Documentation Standards

## Documentation Checklist

### Project Must Have
- [ ] README with quick start ([Required Project Documentation](#required-project-documentation))
- [ ] API reference (OpenAPI spec) ([API Reference](#2-api-reference))
- [ ] Database schema (auto-generated) ([Database Schema Documentation](#3-database-schema-documentation))
- [ ] Environment variables list ([Environment Configuration](#4-environment-configuration))
- [ ] Deployment instructions ([Deployment & Operations](#6-deployment--operations))
- [ ] Architecture diagram ([Required Project Documentation](#required-project-documentation))

### Each Feature Should Have
- [ ] README in feature folder ([Documentation Generation](#documentation-generation))
- [ ] API endpoints documented in code ([API Documentation from Code](#api-documentation-from-code))
- [ ] Database migrations commented ([Database Schema Documentation](#3-database-schema-documentation))
- [ ] Complex logic explained inline ([Documentation Generation](#documentation-generation))

### Each Release Should Have
- [ ] Updated API version if changed ([Required Project Documentation](#required-project-documentation))
- [ ] Migration guide if breaking changes ([Architecture Decision Records (ADRs)](#5-architecture-decision-records-adrs))
- [ ] Updated deployment docs if process changed ([Deployment & Operations](#6-deployment--operations))
- [ ] ADR for significant decisions ([Architecture Decision Records (ADRs)](#5-architecture-decision-records-adrs))

### SSOT Compliance
- [ ] No information duplicated across documents ([SSOT Principles](#ssot-principles))
- [ ] All docs reference single source of truth ([SSOT Patterns](#ssot-patterns))
- [ ] Generated docs automated ([Automated Documentation](#automated-documentation))
- [ ] Links maintained and valid ([SSOT Maintenance Strategy](#ssot-maintenance-strategy))

## Core Philosophy

Documentation is a living system of interconnected guides. Each document has a single purpose and single source of truth. Project-specific docs reference but don't duplicate our core standards. Keep documentation close to code, update it with changes, and automate generation where possible.

## Documentation Hierarchy

### Core Standards (What We've Created)
These are your foundational documents that define HOW to build:

```
standards/                           # Universal principles
├── 01-code-patterns.md            # TypeScript/JS patterns
├── 02-fsd-architecture.md         # Feature-sliced design
├── 03-api-design.md               # API principles
├── 04-database-design.md          # Database & data standards
├── 05-security-standards.md       # Security requirements
├── 06-testing-strategy.md         # Testing approach
├── 07-frontend-architecture.md    # Frontend patterns
├── 08-error-handling.md           # Error handling playbook
├── 09-git-workflow.md             # Version control
├── 10-documentation-standards.md  # This document
└── 11-logging-monitoring.md       # Observability standards
```

### Project-Specific Docs (What You Need to Create)
These implement the standards for YOUR specific application:

```
docs/
├── 02-project-docs/        # Project-specific documentation
│   ├── README.md
│   ├── api/
│   │   ├── reference.md
│   │   ├── authentication.md
│   │   └── examples.md
│   ├── database/
│   │   ├── schema.md
│   │   ├── migrations.md
│   │   └── erd.png
│   ├── architecture/
│   │   ├── system-design.md
│   │   ├── tech-decisions.md
│   │   └── diagrams.md
│   ├── deployment/
│   │   ├── guide.md
│   │   ├── environments.md
│   │   └── rollback.md
│   ├── development/
│   │   ├── setup.md
│   │   ├── testing.md
│   │   └── troubleshooting.md
│   ├── product/                     # Product documentation
│   │   ├── roadmap.md              # Product roadmap & phases
│   │   ├── features/               # Feature-specific docs
│   │   │   ├── [feature-name]/
│   │   │   │   ├── prd-[feature-name].md         # Product requirements
│   │   │   │   └── tdd-[feature-name].md         # Technical design
│   │   └── archived/               # Deprecated features
│   │       └── old-feature/
└── 03-decisions/           # Architecture Decision Records
    ├── 001-tech-stack-overview.md
    ├── 002-choose-react.md
    └── 003-auth-strategy.md
```

## Required Project Documentation

### 1. README.md
Your project's front door.

**What it contains:**
- Project name and one-line description
- Quick start instructions (clone → run)
- Link to all other documentation
- Tech stack overview
- Contact/support info

**What it references:**
- Links to API reference
- Links to architecture docs
- Links to deployment guide

### 2. API Reference
The actual endpoints of your application.

**Format:** OpenAPI/Swagger spec + generated docs

```yaml
# api/openapi.yaml - YOUR specific endpoints
paths:
  /api/v1/users:
    get:
      summary: List users in OUR system
      parameters:
        - name: role
          enum: [admin, member, viewer]  # YOUR roles
  /api/v1/products:
    post:
      summary: Create product in OUR catalog
      requestBody:
        $ref: '#/components/schemas/Product'  # YOUR schema
```

**Generate from code:**
```typescript
// In your actual route files
/**
 * @openapi
 * /api/v1/orders/{id}:
 *   get:
 *     tags: [Orders]
 *     summary: Get order by ID
 *     parameters:
 *       - name: id
 *         in: path
 *         required: true
 *         schema:
 *           type: string
 */
router.get('/orders/:id', getOrder);
```

### 3. Database Schema Documentation
Your actual database structure.

**Auto-generated from migrations:**
```sql
-- Generated file: database/schema.sql
-- Generated at: 2024-01-15
-- From migrations: 001-047

CREATE TABLE users (
    -- Your actual schema
);

CREATE TABLE products (
    -- Your actual schema
);
```

**ERD Diagram:** Use tools like dbdiagram.io or PlantUML
```
// database/erd.dbml
Table users {
  id uuid [pk]
  email varchar [unique, not null]
  created_at timestamp
}

Table orders {
  id uuid [pk]
  user_id uuid [ref: > users.id]
  total decimal
}
```

### 4. Environment Configuration
What YOUR app needs to run.

```markdown
# Environment Variables

## Required
- `DATABASE_URL`: PostgreSQL connection string
- `REDIS_URL`: Redis connection for sessions
- `JWT_SECRET`: Secret for token signing (min 32 chars)

## Optional
- `LOG_LEVEL`: (default: info) debug|info|warn|error
- `PORT`: (default: 3000) Server port

## Feature Flags
- `ENABLE_PREMIUM_FEATURES`: (default: false)
- `ENABLE_ANALYTICS`: (default: true)

See `.env.example` for template
```

### 5. Architecture Decision Records (ADRs)
Document WHY you made specific choices.

```markdown
# ADR-001: Use PostgreSQL for primary database

Status: Accepted
Date: 2024-01-01

## Context
We need to choose a primary database for our application.

## Decision
We will use PostgreSQL 14+.

## Rationale
- Strong ACID compliance for financial data
- JSONB support for flexible schemas
- Excellent performance for our query patterns
- Team has PostgreSQL experience

## Consequences
- Need to manage PostgreSQL instances
- Must handle connection pooling
- Backup strategy required
```

### 6. Deployment & Operations
How to run YOUR specific application.

```markdown
# Deployment Guide

## Prerequisites
- AWS account with correct permissions
- Docker 20.10+
- Terraform 1.0+

## Deployment Steps

### Staging
```bash
./scripts/deploy.sh staging
```

### Production
1. Ensure all tests pass: `npm test`
2. Tag release: `git tag v1.2.0`
3. Deploy: `./scripts/deploy.sh production`
4. Verify: `./scripts/health-check.sh`

## Rollback
```bash
./scripts/rollback.sh <previous-version>
```

## Monitoring
- Dashboards: https://grafana.yourapp.com
- Logs: https://logs.yourapp.com
- Alerts configured in PagerDuty
```

## Documentation Generation

### Automated Documentation
Generate docs from code, don't write twice.

```json
// package.json scripts
{
  "scripts": {
    "docs:api": "swagger-jsdoc -d src/swagger.js -o docs/api/openapi.json 'src/routes/**/*.ts'",
    "docs:db": "pg-to-dbml postgresql://localhost/mydb -o docs/database/schema.dbml",
    "docs:types": "typedoc --out docs/types src",
    "docs:deps": "madge src --image docs/architecture/dependencies.svg",
    "docs:all": "npm run docs:api && npm run docs:db && npm run docs:types"
  }
}
```

### Living Documentation
Keep docs in sync with code.

```typescript
// Feature documentation lives with feature
features/payment/
├── README.md           # How payment feature works
├── api/
│   ├── routes.ts      # Implementation
│   └── routes.test.ts # Tests as documentation
├── docs/
│   ├── stripe-integration.md
│   └── refund-flow.md
```

### API Documentation from Code
```typescript
// Express + Swagger example
import swaggerJsdoc from 'swagger-jsdoc';
import swaggerUi from 'swagger-ui-express';

const specs = swaggerJsdoc({
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'MyApp API',
      version: package.version,
    },
  },
  apis: ['./src/routes/**/*.ts'], // Read from actual route files
});

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));
```


## Single Source of Truth (SSOT) Principles

### SSOT Hierarchy
Each piece of information lives in exactly ONE place.

**Why:** Duplicated information inevitably becomes inconsistent. When docs contradict each other, developers lose trust and stop reading them.

```markdown
# SSOT Hierarchy (highest to lowest priority)

1. CODE - The ultimate truth
   - Types/interfaces are the real API contract
   - Database migrations define actual schema
   - Config files show real settings

2. GENERATED DOCS - Derived from code
   - OpenAPI from route annotations
   - TypeDoc from TypeScript
   - ERD from database schema

3. WRITTEN DOCS - Human context
   - Why decisions were made (ADRs)
   - How to use (guides)
   - Conceptual overview (architecture)
```

### SSOT Patterns

**Pattern 1: Reference, Don't Repeat**
```markdown
# ❌ BAD: Copying information
## User API
Users must have email and password with minimum 12 characters...

# ✅ GOOD: Reference source of truth
## User API
User validation follows [Security Standards](../standards/security.md#password-requirements).
See actual schema: [UserDTO](../src/types/user.ts)
```

**Pattern 2: Generate, Don't Maintain**
```markdown
# ❌ BAD: Manually maintained API docs
## GET /api/users
Returns array of users with id, email, name fields...

# ✅ GOOD: Generated from code
/**
 * @openapi
 * /api/users:
 *   get:
 *     responses:
 *       200:
 *         $ref: '#/components/schemas/User'
 */
router.get('/users', getUsers);
```

**Pattern 3: Link, Don't Duplicate**
```markdown
# ❌ BAD: Explaining external service
## Stripe Integration
Stripe is a payment processor that handles...

# ✅ GOOD: Link to official docs
## Payment Processing
We use [Stripe](https://stripe.com/docs) for payments.
Our implementation: [PaymentService](../src/services/payment.ts)
```

### SSOT Violations to Avoid

**Violation 1: Same info in multiple files**
```markdown
# Found in README.md
Requires Node 18+

# Also in setup.md
Node.js version 18 or higher

# Also in package.json
"engines": { "node": ">=18" }

# FIX: Single source in package.json, others reference it
README: See requirements in package.json
```

**Violation 2: Config in docs and code**
```markdown
# In documentation
Rate limit: 100 requests per minute

# In code
const RATE_LIMIT = 60; // Different!

# FIX: Document references code constant
Rate limit: See RATE_LIMIT in [config.ts](../src/config.ts)
```

**Violation 3: Business rules scattered**
```markdown
# In API docs
Orders over $100 get free shipping

# In frontend
if (order.total > 150) // Different threshold!

# In backend
const FREE_SHIPPING_MIN = 125; // Another value!

# FIX: Single source in shared config
shared/business-rules.ts:
export const FREE_SHIPPING_THRESHOLD = 100;
```

### SSOT Maintenance Strategy

**1. Establish Ownership**
```markdown
| Information Type | Source of Truth | Owner |
|-----------------|-----------------|--------|
| API Contract | OpenAPI spec | Backend team |
| UI Components | Storybook | Frontend team |
| Business Rules | business-rules.ts | Product team |
| Infrastructure | Terraform files | DevOps team |
| Security Policies | security.md | Security team |
```

**2. Audit for Violations**
```bash
# Find potential duplications
grep -r "Node.js\|node version" docs/

# Find hardcoded values that should be centralized
grep -r "100\|rate limit\|threshold" --include="*.md"

# Check for outdated examples
grep -r "example.com\|TODO\|FIXME" docs/
```

**3. Create Source Mapping**
```markdown
# docs/source-map.md

## Where to Find Truth

| Topic | Source of Truth | Generated Docs |
|-------|----------------|----------------|
| API Endpoints | src/routes/*.ts | /api-docs |
| Database Schema | migrations/*.sql | docs/db/schema.html |
| Types | src/types/*.ts | docs/types/ |
| Environment Vars | src/config.ts | From code comments |
| Business Logic | src/rules/*.ts | N/A |
| Error Codes | src/errors/codes.ts | docs/errors.md |
```

### SSOT Decision Tree

```
Need to document something?
├─ Is it derived from code?
│  ├─ YES → Generate it automatically
│  └─ NO → Continue
│
├─ Does it exist elsewhere?
│  ├─ YES → Link to it, don't copy
│  └─ NO → Continue
│
├─ Will it change with code?
│  ├─ YES → Put in code as comments/types
│  └─ NO → Continue
│
├─ Is it external knowledge?
│  ├─ YES → Link to official source
│  └─ NO → Create new documentation
│
└─ This is unique human context → Write it once
```

### Enforcing SSOT

**Pre-commit hooks:**
```json
{
  "husky": {
    "hooks": {
      "pre-commit": "npm run docs:check-ssot"
    }
  }
}
```

**SSOT check script:**
```typescript
// scripts/check-ssot.ts
const violations = [
  checkForDuplicateVersions(),
  checkForHardcodedConfigs(),
  checkForOutdatedApiDocs(),
  checkForConflictingRules()
];

if (violations.length > 0) {
  console.error('SSOT violations found:', violations);
  process.exit(1);
}
```

## Documentation Lifecycle Decisions

### When to Create New Documentation

**Create a new document when:**
- **New domain appears** - Adding payments? Create `payments.md`
- **Complexity threshold hit** - Section in README > 100 lines? Extract to own file
- **Different audience** - Developers vs DevOps vs Business stakeholders need different docs
- **Different update frequency** - Deployment guide changes weekly, architecture monthly
- **Discoverability improves** - Hard to find info buried in large doc

**Examples of new doc triggers:**
```markdown
# Before: Everything in README (getting too long)
README.md (500+ lines)
- Getting started
- API documentation  
- Deployment steps
- Troubleshooting
- Architecture

# After: Separated by concern
README.md (50 lines with links)
api/reference.md
deployment/guide.md
troubleshooting.md
architecture/overview.md
```

### When to Update Existing Documentation

**Update existing when:**
- **Implementation changes** - API endpoint modified? Update api/reference.md
- **Process changes** - New deployment step? Update deployment guide
- **Clarification needed** - Support tickets about same issue? Improve that section
- **Deprecation** - Mark old patterns as deprecated, don't delete immediately
- **Better examples found** - Replace confusing examples with clearer ones

**Update patterns:**
```markdown
# Mark deprecation clearly
## User Authentication ⚠️ DEPRECATED
**Deprecated since:** v2.0.0  
**Use instead:** [OAuth Authentication](#oauth-authentication)  
**Will be removed:** v3.0.0

[Old documentation kept for migration period]

## OAuth Authentication (Current)
[New approach documented here]
```

### When NOT to Create New Documentation

**Don't create new docs for:**
- **Temporary solutions** - Document in code comments
- **Standard patterns** - Reference existing standards
- **External services** - Link to official docs
- **One-time processes** - Put in PR description
- **Obvious code** - Self-documenting code needs no doc

**Anti-patterns to avoid:**
```markdown
# ❌ BAD: Creating new doc for standard pattern
docs/how-to-write-react-components.md  # Just follow standards

# ❌ BAD: Duplicating external documentation  
docs/stripe-api-guide.md  # Link to Stripe's docs

# ❌ BAD: Over-documenting
docs/how-to-create-a-button.md  # Too granular
```

### Documentation Refactoring Signals

**Time to refactor when:**
- **Can't find info quickly** - Poor organization
- **Same info in multiple places** - SSOT violation
- **Outdated sections everywhere** - Too many docs to maintain
- **Conflicting information** - Docs disagree with each other
- **No one uses the docs** - Wrong format or location

**Refactoring strategies:**
```markdown
# Consolidation: Multiple small docs → One comprehensive doc
auth-basic.md + auth-oauth.md + auth-jwt.md → authentication.md

# Separation: One large doc → Multiple focused docs
giant-api-doc.md → 
  - api/users.md
  - api/products.md  
  - api/orders.md

# Automation: Manual docs → Generated docs
manually-maintained-api.md → OpenAPI spec + Swagger UI
```

### Documentation Review Triggers

**Review and update docs when:**
- **Major release** - Version 2.0 released
- **Incident post-mortem** - Docs contributed to issue?
- **New team member confused** - Onboarding reveals gaps
- **Quarter/sprint end** - Regular review cycle
- **Architecture change** - System design modified

**Review checklist:**
```markdown
## Quarterly Documentation Review

- [ ] README still accurate for quick start?
- [ ] API docs match current implementation?
- [ ] Deprecated sections removed (past removal date)?
- [ ] New features documented?
- [ ] Runbook covers recent incidents?
- [ ] Links still working?
- [ ] Examples still valid?
- [ ] Generated docs rebuilding correctly?
```

## Documentation Rules

### Single Source of Truth
- **DON'T** copy from standards into project docs
- **DO** reference standards and show implementation
- **DON'T** document the same thing in multiple places
- **DO** link between related documents

### Keep It Current
- **DON'T** write documentation "later"
- **DO** update docs in the same PR as code changes
- **DON'T** manually maintain what can be generated
- **DO** automate documentation from code where possible

### Make It Discoverable
- **DON'T** hide docs in random folders
- **DO** follow consistent structure
- **DON'T** assume people know where to look
- **DO** link liberally between documents

## Example: Implementing Standards

### Bad: Duplicating Standards
```markdown
# API Documentation

## REST Principles
REST APIs should use HTTP methods... [copying from standards]
```

### Good: Implementing Standards
```markdown
# API Documentation

This API follows our [API Design Principles](../standards/api-design.md).

## Base URL
Production: `https://api.myapp.com/v1`

## Authentication
We implement Bearer token auth as per security standards:
- Tokens expire after 1 hour
- Refresh tokens valid for 7 days

## Endpoints

### GET /users
Returns paginated user list...
[specific to YOUR application]
```