Documentation Restructure

reference/foundations/documentation-restructure-proposal.md

@@ -0,0 +1,113 @@
+---
+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)
+```text
+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.