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

# 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

# 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

# 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

# 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

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

# 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

# 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

# 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

# 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