Delete reference/foundations/Documentation Restructure Proposal.md
Automatic Documentation Deployment / Sync Docs to https://kb.bunny-lab.io (push) Successful in 25s
Automatic Documentation Deployment / Sync Docs to https://kb.bunny-lab.io (push) Successful in 25s
This commit is contained in:
@@ -1,113 +0,0 @@
|
|||||||
---
|
|
||||||
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.
|
|
||||||
Reference in New Issue
Block a user