server-ovh-prod-01-main/docs/documentation-maintenance.md

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

# 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:

| **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 - Most frequently updated doc
• Configuration Reference - Template documentation
• CLAUDE.md - Core principles that rarely change
• Migration Plan - Phase tracking