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