docs/reference/foundations/documentation-restructure-proposal.md

tags

tags
Documentation Foundations Restructure

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:
   • By domain (Platforms, Services, Infrastructure)
   • By purpose (Operations, Reference, Deployment, Scripts)
2. Task-oriented docs are scattered:
   • Example: deployment docs exist in Platforms, Services, and Operations/Automation/.../Deployment.
3. Naming/link style drift is high:
   • Many links use lowercase-kebab paths while files still use title case and spaces.
   • 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
   • Lock naming convention: lowercase-kebab-case directories and files.
   • Move only index pages first (10 files) to establish new top nav.
2. Phase 1: move scripts (39 files)
   • Lowest blast radius, immediate usability improvement.
3. Phase 2: move workflows (37 files)
   • Consolidates day-2 operations and runbooks.
4. Phase 3: move deployments (85 files)
   • Largest move set, do after scripts/workflows are stable.
5. Phase 4: cleanup and verification
   • 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.