273 lines
8.9 KiB
Markdown
273 lines
8.9 KiB
Markdown
# 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
|