proxmox/docs/00-meta/MARKDOWN_FILE_MAINTENANCE_GUIDE.md

Markdown File Maintenance Guide

Last Updated: 2026-01-31
Document Version: 1.0
Status: Active Documentation

---

Last Updated: 2026-01-05
Purpose: Guidelines for maintaining clean, organized markdown files

---

File Organization Standards

Root Directory (/)

Should contain ONLY:

• README.md - Main project README
• PROJECT_STRUCTURE.md - Project structure documentation

Should NOT contain:

• Status reports
• Completion reports
• Analysis reports
• Timestamped snapshots
• Temporary fix guides

Documentation Directory (docs/)

Should contain:

• Permanent documentation
• Architecture guides
• Configuration guides
• Tutorials and how-tos
• API documentation

Should NOT contain:

• Status/completion reports (→ reports/)
• Temporary fix guides (→ docs/09-troubleshooting/archive/)
• Timestamped snapshots (→ reports/archive/)

Reports Directory (reports/)

Should contain:

• All status reports
• All analysis reports
• All diagnostic reports
• Timestamped snapshots (in archive/ subdirectories)

Structure:

reports/
├── status/          # Current status reports
├── analyses/        # Analysis reports
├── inventories/     # Inventory reports
└── archive/         # Archived reports by date
    └── YYYY-MM-DD/  # Date-specific archives

Submodule Directories

Each submodule should have:

• README.md - Submodule documentation
• docs/ - Submodule-specific documentation
• reports/ or archive/ - Status/completion files

---

File Naming Conventions

Documentation Files

• Use UPPERCASE_WITH_UNDERSCORES.md
• Be descriptive: NETWORK_ARCHITECTURE.md not network.md
• Use consistent prefixes:
  • README.md - Directory overview
  • QUICK_START.md - Quick start guide
  • DEPLOYMENT.md - Deployment guide
  • TROUBLESHOOTING.md - Troubleshooting guide

Status/Report Files

• Use descriptive names: SERVICE_STATUS.md not status.md
• Avoid timestamps in filenames (use archive directories instead)
• Use consistent suffixes:
  • *_STATUS.md - Current status
  • *_REPORT.md - Analysis report
  • *_SUMMARY.md - Summary report

Temporary Files

• Prefix with TEMP_ or ARCHIVE_
• Move to archive directories promptly
• Delete after 90 days if no longer needed

---

When to Create Files

✅ Create Documentation When:

• Documenting a new feature or component
• Creating a guide or tutorial
• Documenting architecture or design decisions
• Creating API documentation

✅ Create Reports When:

• Generating status reports
• Creating analysis reports
• Documenting diagnostic findings
• Creating inventory snapshots

❌ Don't Create Files For:

• Temporary notes (use issue tracker or notes app)
• One-time commands (use scripts)
• Duplicate status (update existing file)
• Placeholder content (wait until content is ready)

---

When to Archive Files

Archive When:

• File is older than 90 days AND superseded by newer version
• File is a timestamped snapshot
• File documents a completed task (not ongoing)
• File is a temporary fix guide (issue resolved)

Archive Location:

• reports/archive/YYYY-MM-DD/ - For dated reports
• docs/09-troubleshooting/archive/ - For resolved troubleshooting guides
• {submodule}/docs/archive/ - For submodule-specific archives

Archive Naming:

• Keep original filename
• Add date prefix if needed: YYYY-MM-DD_original-name.md
• Create README.md in archive directory explaining contents

---

When to Delete Files

Safe to Delete:

• Duplicate files (keep most recent)
• Empty or placeholder files
• Files marked as deprecated
• Old temporary files (>90 days, archived)

Never Delete:

• README.md files
• Active documentation
• Files referenced by other files
• Files in git history (use git to remove)

---

Maintenance Checklist

Weekly

• Review root directory for misplaced files
• Archive timestamped snapshots older than 7 days
• Check for duplicate status files

Monthly

• Review reports/ organization
• Archive completed status reports
• Update cross-references
• Check for broken links

Quarterly

• Review archive directories
• Delete old temporary files (>90 days)
• Consolidate duplicate documentation
• Update file organization standards

---

Automated Maintenance

Analysis Scripts

# Analyze all markdown files
python3 scripts/analyze-markdown-files.py

# Check for inconsistencies
python3 scripts/check-content-inconsistencies.py

# Cleanup files
bash scripts/cleanup-markdown-files.sh

Git Hooks (Optional)

Create .git/hooks/pre-commit to check for:

• Files in wrong directories
• Broken cross-references
• Placeholder content

---

Common Issues and Solutions

Issue: Too many files in root

Solution: Move status/report files to reports/

Issue: Duplicate status files

Solution: Consolidate to single status file per component

Issue: Broken cross-references

Solution: Update links or move files to correct location

Issue: Outdated content

Solution: Archive or update with current information

Issue: Temporary files accumulating

Solution: Archive or delete after 90 days

---

Best Practices

1. One Source of Truth: Don't duplicate status information
2. Clear Organization: Follow directory structure standards
3. Descriptive Names: Use clear, consistent file names
4. Regular Cleanup: Archive or delete old files regularly
5. Cross-Reference: Keep links between related files updated
6. Document Decisions: Explain why files are organized as they are

---

Quick Reference

File Locations

Type	Location
Main README	/README.md
Project Structure	/PROJECT_STRUCTURE.md
Documentation	/docs/
Status Reports	/reports/status/
Analysis Reports	/reports/analyses/
Archived Reports	/reports/archive/YYYY-MM-DD/
Temporary Fixes	/docs/09-troubleshooting/archive/

Commands

# Count markdown files
find . -name "*.md" -type f | wc -l

# Find files in root
find . -maxdepth 1 -name "*.md" -type f

# Find duplicate names
find . -name "*.md" -type f | xargs basename | sort | uniq -d

# Check for broken links (requires markdown-link-check)
find . -name "*.md" -type f -exec markdown-link-check {} \;

---

Questions?

• Review MARKDOWN_FILES_COMPREHENSIVE_REPORT.md for detailed analysis
• Check CONTENT_INCONSISTENCIES.json for specific issues
• Run analysis scripts for current status

---

Maintained By: Project Team
Last Review: 2026-01-05