Nicole Rappe
51cdd1fdb6
All checks were successful
Automatic Documentation Deployment / Sync Docs to https://kb.bunny-lab.io (push) Successful in 5s
114 lines
3.5 KiB
Markdown
114 lines
3.5 KiB
Markdown
---
|
|
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.
|