Documentation Restructure Proposal (v2)¶

Audit Snapshot (2026-02-26)¶

• Total markdown files: 197
• Current root split:
• Operations: 77
• Services: 71
• Infrastructure: 22
• Platforms: 21
• Blog: 5
• Root index.md: 1
• Broken relative markdown links found: 38
• Proposed type split:
• deployments: 85
• workflows: 37
• scripts: 39
• reference: 22
• blog: 4
• index: 10

Why Navigation Feels Hard¶

1. The current structure mixes two different axes:
2. By domain (Platforms, Services, Infrastructure)
3. By purpose (Operations, Reference, Deployment, Scripts)
4. Task-oriented docs are scattered:
5. Example: deployment docs exist in Platforms, Services, and Operations/Automation/.../Deployment.
6. Naming/link style drift is high:
7. Many links use lowercase-kebab paths while files still use title case and spaces.
8. This mismatch is a major contributor to broken links and poor discoverability.

Target IA (Content-Type First)¶

index.md
blog/
  index.md
  posts/

deployments/
  index.md
  platforms/
  services/
  automation/

workflows/
  index.md
  operations/
  platforms/

scripts/
  index.md
  bash/
  powershell/
  batch/
  services/

reference/
  index.md
  foundations/
  infrastructure/

Folder Mapping Rules¶

1. Operations/Reference/** -> scripts/**
2. Services/**/Scripts/** -> scripts/services/**
3. Operations/** (except reference + deployment docs) -> workflows/operations/**
4. Platform operations/day-2 docs -> workflows/platforms/**
5. Platforms/** deployment/setup docs -> deployments/platforms/**
6. Services/** deployment/setup docs -> deployments/services/**
7. Operations/Automation/**/Deployment/** -> deployments/automation/**
8. Infrastructure/** + Operations/Foundations/** -> reference/**
9. Normalize all destination paths to lowercase-kebab-case.

Generated Migration Artifact¶

• Full proposed path map: reference/foundations/documentation-restructure-migration-map.csv
• Columns:
• current_path
• proposed_path
• doc_type
• confidence
• reason

Manual Review Queue (Medium Confidence)¶

1. Platforms/Containerization/Kubernetes/Migrating Docker Compose YML to K8s.md
2. Platforms/Virtualization/Hyper V/Failover Cluster/Rebuild Failover Cluster Replication.md
3. Platforms/Virtualization/Hyper V/Forcefully Stop GuestVM.md
4. Platforms/Virtualization/Hyper V/Kerberos Enabled VM Migration.md
5. Platforms/Virtualization/Proxmox/Common Tasks.md

Phased Migration Sequence¶

1. Phase 0: stabilize naming and links
2. Lock naming convention: lowercase-kebab-case directories and files.
3. Move only index pages first (10 files) to establish new top nav.
4. Phase 1: move scripts (39 files)
5. Lowest blast radius, immediate usability improvement.
6. Phase 2: move workflows (37 files)
7. Consolidates day-2 operations and runbooks.
8. Phase 3: move deployments (85 files)
9. Largest move set, do after scripts/workflows are stable.
10. Phase 4: cleanup and verification
11. Fix all internal links, remove old folders, and validate build output.

Guardrails For Future Docs¶

1. Keep one primary intent per doc: deployment, workflow, script, or reference.
2. Require an index.md in every first-level and second-level folder.
3. Use stable cross-links with root-relative paths after migration.
4. Avoid adding new docs to legacy roots once migration starts.