# Documentation Maintenance Guide

This meta-document describes when and how to keep the server documentation current. Following these guidelines ensures documentation remains accurate and useful for both humans and AI assistants.

## Documentation Structure

```
/home/jared/projects/server-ovh-prod-01/
├── CLAUDE.md                          # Core principles (rarely changes)
├── README.md                          # Quick reference
├── profile.yaml                       # Server specifications
├── credentials.md                     # Access credentials
├── docs/                              # Specialized documentation
│   ├── services-inventory.md          # 🔄 DYNAMIC - Update frequently
│   ├── wordpress-operations.md        # Reference guide
│   ├── monitoring-automation.md       # Operations reference
│   ├── configuration-reference.md     # Template catalog
│   └── documentation-maintenance.md   # This file
├── migrations/
│   └── migration-plan.md              # 🔄 DYNAMIC - Update per phase
└── configs/                           # Templates and examples
```

## Update Frequency

| Document | Update Frequency | Trigger |
|----------|------------------|---------|
| `CLAUDE.md` | Rarely | Architecture changes, new patterns |
| `services-inventory.md` | **Every deployment** | Service added/removed/changed |
| `migration-plan.md` | Per migration phase | Service migration completed |
| `profile.yaml` | Monthly or on change | Server upgrades, config changes |
| `wordpress-operations.md` | As needed | New WordPress patterns discovered |
| `monitoring-automation.md` | As needed | Monitoring script changes |
| `configuration-reference.md` | When adding templates | New service type added |
| `README.md` | As needed | Major project updates |

## When to Update Each Document

### After Deploying a New Service

**Checklist:**
- [ ] Update `docs/services-inventory.md`
  - Add service to Active Services table
  - Update directory structure if new location
  - Update "Last Updated" date
- [ ] Update `migrations/migration-plan.md` (if migrating)
  - Mark service as completed
  - Update phase status
  - Add any lessons learned
- [ ] Consider updating `README.md`
  - Add to "Live Services" section if user-facing
- [ ] Create template if it's a new service type
  - Add to `configs/`
  - Document in `configuration-reference.md`

### After Removing/Decommissioning a Service

**Checklist:**
- [ ] Update `docs/services-inventory.md`
  - Remove from Active Services table
  - Update directory structure
  - Update "Last Updated" date
- [ ] Update `README.md`
  - Remove from "Live Services" if listed
- [ ] Archive service documentation
  - Move deployment notes to `migrations/completed/`
  - Keep for reference

### After Changing Service Configuration

**Checklist:**
- [ ] Update `docs/services-inventory.md` if:
  - Domain changed
  - Container names changed
  - Service type changed
- [ ] Update `credentials.md` if:
  - Passwords changed
  - Access methods changed
- [ ] Update relevant template in `configs/` if:
  - Configuration pattern improved
  - Discovered better approach

### After Server Upgrades/Changes

**Checklist:**
- [ ] Update `profile.yaml`
  - Software versions
  - Resource allocations
  - Network configurations
- [ ] Update `CLAUDE.md` if:
  - Architecture patterns changed
  - New best practices established
  - Critical commands changed

### After Discovering New Patterns/Solutions

**Checklist:**
- [ ] Update `docs/wordpress-operations.md` if:
  - WordPress-specific discovery
  - New troubleshooting solution
- [ ] Update `docs/monitoring-automation.md` if:
  - Monitoring script changes
  - New health check patterns
- [ ] Update `docs/configuration-reference.md` if:
  - New Docker Compose pattern
  - Traefik label improvements
- [ ] Consider updating `CLAUDE.md` if:
  - Pattern applies broadly across all services
  - Changes fundamental workflow

## How to Update Services Inventory

The `docs/services-inventory.md` file changes most frequently. Here's how to keep it current:

### Quick Update Process

```bash
# 1. Get current state from server
ssh jared@15.204.247.153 "docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'"

# 2. Edit services-inventory.md locally
# Add/remove/update services in the table

# 3. Update the "Last Updated" date
# At the top of services-inventory.md

# 4. Commit changes
git add docs/services-inventory.md
git commit -m "Update services inventory: [describe change]"
```

### Service Entry Template

When adding a new service to the inventory:

```markdown
| **servicename** | Type | domain.com | `container_app`<br>`container_db` | ✅ Running | Brief note |
```

**Fields:**
- **Service name** - Lowercase, matches directory name
- **Type** - WordPress, Web App, Database, etc.
- **Domain(s)** - Primary domain (use `<br>` for multiple)
- **Containers** - List all containers (use `<br>` for multiple)
- **Status** - ✅ Running, ⚠️ Degraded, ❌ Stopped
- **Notes** - Brief deployment note or purpose

## Keeping CLAUDE.md Lean

**CLAUDE.md should remain small and focused.** Before adding content to CLAUDE.md, ask:

1. **Is this used in almost every session?** → Add to CLAUDE.md
2. **Is this reference material?** → Add to specialized doc
3. **Is this dynamic/changing?** → Definitely NOT in CLAUDE.md
4. **Is this service-specific?** → Add to specialized doc

**Examples:**
- ✅ Add to CLAUDE.md: SSH command, core architecture principles
- ❌ Don't add to CLAUDE.md: WordPress URL change commands, current service list

## AI Assistant Guidelines

When an AI assistant (like Claude Code) needs to update documentation:

### Always Update
- `services-inventory.md` after any service deployment/removal
- `migration-plan.md` after completing migration tasks
- Relevant timestamp/date fields

### Selectively Update
- Operation-specific docs only when discovering new patterns
- Templates only when creating reusable configurations
- `CLAUDE.md` only for architectural changes

### Never Update Without Asking
- `credentials.md` (security sensitive)
- `profile.yaml` (factual server data)
- Removing existing content from docs

## Git Commit Practices

### Commit Messages for Documentation

**Good examples:**
```
docs: Update services inventory - add invoiceninja
docs: Add WordPress SSL troubleshooting to operations guide
docs: Remove decommissioned landhometeam from inventory
docs: Update migration plan - Phase 3.3 complete
```

**Follow pattern:**
```
docs: <brief description of what changed>
```

### When to Commit

- After each service deployment/removal
- After completing documentation updates
- Before starting a new migration phase
- When adding new templates or guides

### What NOT to Commit

- Temporary files
- Sensitive credentials (use .gitignore)
- AI assistant output logs
- Personal notes not relevant to project

## Documentation Quality Standards

### Writing Style
- **Clear and concise** - Get to the point quickly
- **Action-oriented** - Use commands and examples
- **Assume remote context** - Remember server is remote (15.204.247.153)
- **Include copy-paste examples** - Make commands easily executable

### Structure Standards
- **Use headers** - Break content into scannable sections
- **Use tables** - For structured data (services, specs, etc.)
- **Use code blocks** - For all commands and configs
- **Use checklists** - For procedural steps

### Link Standards
- **Use relative links** - `./other-doc.md` not absolute paths
- **Keep cross-references** - Help readers find related info
- **Verify links work** - Test links after structural changes

## Review Schedule

**Monthly Review:**
- [ ] Verify `services-inventory.md` matches actual server state
- [ ] Check `profile.yaml` reflects current configuration
- [ ] Review `migration-plan.md` status is current
- [ ] Scan logs for patterns worthy of documentation

**Quarterly Review:**
- [ ] Review all docs for accuracy
- [ ] Remove obsolete content
- [ ] Update examples with current versions
- [ ] Consolidate redundant information

## Troubleshooting Documentation Issues

### Stale Information
**Problem:** Documentation doesn't match reality
**Solution:**
1. Verify current state via SSH commands
2. Update affected documents
3. Note in commit message what was stale

### Missing Information
**Problem:** Documentation gap discovered
**Solution:**
1. Determine appropriate document location
2. Add missing information with examples
3. Cross-reference from related docs

### Conflicting Information
**Problem:** Different docs say different things
**Solution:**
1. Verify which is correct via server inspection
2. Update all conflicting locations
3. Consider consolidating if too scattered

## See Also

- [Services Inventory](./services-inventory.md) - Most frequently updated doc
- [Configuration Reference](./configuration-reference.md) - Template documentation
- [CLAUDE.md](../CLAUDE.md) - Core principles that rarely change
- [Migration Plan](../migrations/migration-plan.md) - Phase tracking