homelab-optimized/docs/admin/DOCUMENTATION_MAINTENANCE_GUIDE.md

# 📚 Documentation Maintenance Guide

*Comprehensive guide for maintaining homelab documentation across all systems*

## 🎯 Overview

This guide covers the maintenance procedures for keeping documentation synchronized and up-to-date across all three documentation systems:

1. **Git Repository** (Primary source of truth)
2. **DokuWiki Mirror** (Web-based access)
3. **Gitea Wiki** (Native Git integration)

## 🏗️ Documentation Architecture

### System Hierarchy
```
📚 Documentation Systems
├── 🏠 Git Repository (git.vish.gg/Vish/homelab)
│   ├── Status: ✅ Primary source of truth
│   ├── Location: /home/homelab/organized/repos/homelab/docs/
│   └── Structure: Organized hierarchical folders
│
├── 🌐 DokuWiki Mirror (atlantis.vish.local:8399)
│   ├── Status: ✅ Fully operational (160 pages)
│   ├── Sync: Manual via scripts/sync-dokuwiki-simple.sh
│   └── Access: Web interface, collaborative editing
│
└── 📖 Gitea Wiki (git.vish.gg/Vish/homelab/wiki)
    ├── Status: 🔄 Partially organized (364 pages)
    ├── Sync: API-based via Gitea token
    └── Access: Native Git integration
```

## 🔄 Synchronization Procedures

### 1. DokuWiki Synchronization

#### Full Sync Process
```bash
# Navigate to repository
cd /home/homelab/organized/repos/homelab

# Run DokuWiki sync script
./scripts/sync-dokuwiki-simple.sh

# Verify installation
ssh -p 60000 vish@192.168.0.200 "
  curl -s 'http://localhost:8399/doku.php?id=homelab:start' | grep -E 'title' | head -1
"
```

#### Manual Page Upload
```bash
# Convert single markdown file to DokuWiki
convert_md_to_dokuwiki() {
    local input_file="$1"
    local output_file="$2"
    
    sed -e 's/^# \(.*\)/====== \1 ======/' \
        -e 's/^## \(.*\)/===== \1 =====/' \
        -e 's/^### \(.*\)/==== \1 ====/' \
        -e 's/^#### \(.*\)/=== \1 ===/' \
        -e 's/\*\*\([^*]*\)\*\*/\*\*\1\*\*/g' \
        -e 's/\*\([^*]*\)\*/\/\/\1\/\//g' \
        -e 's/`\([^`]*\)`/%%\1%%/g' \
        -e 's/^- \[x\]/  * ✅/' \
        -e 's/^- \[ \]/  * ☐/' \
        -e 's/^- /  * /' \
        "$input_file" > "$output_file"
}
```

### 2. Gitea Wiki Management

#### API Authentication
```bash
# Set Gitea API token
export GITEA_TOKEN=REDACTED_TOKEN
export GITEA_URL="https://git.vish.gg"
export REPO_OWNER="Vish"
export REPO_NAME="homelab"
```

#### Create/Update Wiki Pages
```bash
# Create new wiki page
create_wiki_page() {
    local page_name="$1"
    local content="$2"
    
    curl -X POST "$GITEA_URL/api/v1/repos/$REPO_OWNER/$REPO_NAME/wiki" \
        -H "Authorization: token $GITEA_TOKEN" \
        -H "Content-Type: application/json" \
        -d "{
            \"title\": \"$page_name\",
            \"content_base64\": \"$(echo -n "$content" | base64 -w 0)\",
            \"message\": \"Update $page_name documentation\"
        }"
}
```

## 📊 Current Status Assessment

### Documentation Coverage Analysis

#### Repository Structure (✅ Complete)
```
docs/
├── admin/           # 23 files - Administration guides
├── advanced/        # 9 files - Advanced topics
├── getting-started/ # 8 files - Beginner guides
├── hardware/        # 5 files - Hardware documentation
├── infrastructure/  # 25 files - Infrastructure guides
├── runbooks/        # 7 files - Operational procedures
├── security/        # 2 files - Security documentation
├── services/        # 15 files - Service documentation
└── troubleshooting/ # 18 files - Troubleshooting guides
```

#### DokuWiki Status (✅ Synchronized)
- **Total Pages**: 160 pages successfully synced
- **Structure**: Hierarchical namespace organization
- **Last Sync**: February 14, 2026
- **Access**: http://atlantis.vish.local:8399/doku.php?id=homelab:start

#### Gitea Wiki Status (🔄 Needs Cleanup)
- **Total Pages**: 364 pages (many outdated/duplicate)
- **Structure**: Flat list requiring reorganization
- **Issues**: Missing category pages, broken navigation
- **Priority**: Medium - functional but needs improvement

## 🛠️ Maintenance Tasks

### Daily Tasks
- [ ] Check for broken links in documentation
- [ ] Verify DokuWiki accessibility
- [ ] Monitor Gitea Wiki for spam/unauthorized changes

### Weekly Tasks
- [ ] Review and update operational status documents
- [ ] Sync any new documentation to DokuWiki
- [ ] Check documentation metrics and usage

### Monthly Tasks
- [ ] Full documentation audit
- [ ] Update service inventory and status
- [ ] Review and update troubleshooting guides
- [ ] Clean up outdated Gitea Wiki pages

### Quarterly Tasks
- [ ] Comprehensive documentation reorganization
- [ ] Update all architecture diagrams
- [ ] Review and update security documentation
- [ ] Performance optimization of documentation systems

## 🔍 Quality Assurance

### Documentation Standards
1. **Consistency**: Use standardized templates and formatting
2. **Accuracy**: Verify all procedures and commands
3. **Completeness**: Ensure all services are documented
4. **Accessibility**: Test all links and navigation
5. **Currency**: Keep status indicators up to date

### Review Checklist
```markdown
## Documentation Review Checklist

### Content Quality
- [ ] Information is accurate and current
- [ ] Procedures have been tested
- [ ] Links are functional
- [ ] Code examples work as expected
- [ ] Screenshots are current (if applicable)

### Structure & Navigation
- [ ] Proper heading hierarchy
- [ ] Clear table of contents
- [ ] Cross-references are accurate
- [ ] Navigation paths are logical

### Formatting & Style
- [ ] Consistent markdown formatting
- [ ] Proper use of status indicators (✅ 🔄 ⚠️ ❌)
- [ ] Code blocks are properly formatted
- [ ] Lists and tables are well-structured

### Synchronization
- [ ] Changes reflected in all systems
- [ ] DokuWiki formatting is correct
- [ ] Gitea Wiki links are functional
```

## 🚨 Troubleshooting

### Common Issues

#### DokuWiki Sync Failures
```bash
# Check DokuWiki accessibility
curl -I http://atlantis.vish.local:8399/doku.php?id=homelab:start

# Verify SSH access to Atlantis
ssh -p 60000 vish@192.168.0.200 "echo 'SSH connection successful'"

# Check DokuWiki data directory permissions
ssh -p 60000 vish@192.168.0.200 "
  ls -la /volume1/@appdata/REDACTED_APP_PASSWORD/all_shares/metadata/docker/dokuwiki/dokuwiki/data/pages/
"
```

#### Gitea Wiki API Issues
```bash
# Test API connectivity
curl -H "Authorization: token $GITEA_TOKEN" \
  "$GITEA_URL/api/v1/repos/$REPO_OWNER/$REPO_NAME/wiki"

# Verify token permissions
curl -H "Authorization: token $GITEA_TOKEN" \
  "$GITEA_URL/api/v1/user"
```

#### Repository Sync Issues
```bash
# Check Git status
git status
git log --oneline -5

# Verify remote connectivity
git remote -v
git fetch origin
```

## 📈 Metrics and Monitoring

### Key Performance Indicators
1. **Documentation Coverage**: % of services with complete documentation
2. **Sync Frequency**: How often documentation is synchronized
3. **Access Patterns**: Which documentation is most frequently accessed
4. **Update Frequency**: How often documentation is updated
5. **Error Rates**: Sync failures and broken links

### Monitoring Commands
```bash
# Count total documentation files
find docs/ -name "*.md" | wc -l

# Check for broken internal links
grep -r "\[.*\](.*\.md)" docs/ | grep -v "http" | while read line; do
    file=$(echo "$line" | cut -d: -f1)
    link=$(echo "$line" | sed 's/.*](\([^)]*\)).*/\1/')
    if [[ ! -f "$(dirname "$file")/$link" ]] && [[ ! -f "$link" ]]; then
        echo "Broken link in $file: $link"
    fi
done

# DokuWiki health check
curl -s http://atlantis.vish.local:8399/doku.php?id=homelab:start | \
  grep -q "homelab:start" && echo "✅ DokuWiki OK" || echo "❌ DokuWiki Error"
```

## 🔮 Future Improvements

### Automation Opportunities
1. **Git Hooks**: Automatic DokuWiki sync on repository push
2. **Scheduled Sync**: Cron jobs for regular synchronization
3. **Health Monitoring**: Automated documentation health checks
4. **Link Validation**: Automated broken link detection

### Enhanced Features
1. **Bidirectional Sync**: Allow DokuWiki edits to flow back to Git
2. **Version Control**: Better tracking of documentation changes
3. **Search Integration**: Unified search across all documentation systems
4. **Analytics**: Usage tracking and popular content identification

## 📞 Support and Escalation

### Contact Information
- **Repository Issues**: https://git.vish.gg/Vish/homelab/issues
- **DokuWiki Access**: http://atlantis.vish.local:8399
- **Emergency Access**: SSH to vish@192.168.0.200:60000

### Escalation Procedures
1. **Minor Issues**: Create repository issue with "documentation" label
2. **Sync Failures**: Check system status and retry
3. **Major Outages**: Follow emergency access procedures
4. **Data Loss**: Restore from Git repository (source of truth)

---

**Last Updated**: February 14, 2026  
**Next Review**: March 14, 2026  
**Maintainer**: Homelab Administrator  
**Status**: ✅ Active and Operational