d-bis/proxmox
4
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
master
proxmox/docs/00-meta/DOCUMENTATION_CONSOLIDATION_PLAN.md
defiQUG b3a8fe4496
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
Details
chore: sync all changes to Gitea 
- Config, docs, scripts, and backup manifests
- Submodule refs unchanged (m = modified content in submodules)

Made-with: Cursor
2026-03-02 11:37:34 -08:00

160 lines
10 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Documentation Consolidation Plan
**Last Updated:** 2026-03-02
**Purpose:** Review, consolidate, and prune markdown docs. Single reference for what to keep, merge, or archive.
**Related:** [ARCHIVE_CANDIDATES.md](ARCHIVE_CANDIDATES.md) | [archive/00-meta-pruned/README.md](../archive/00-meta-pruned/README.md). (Dated review docs, e.g. DOCUMENTATION_REVIEW_20260216, are in archive/00-meta-pruned.)
---
## 1. Scope
- **Primary:** `docs/` (root + 00-meta through 12-quick-reference, gru-m1, compliance, runbooks, archive).
- **Verification evidence:** Keep recent runs; older runs already in `archive/verification-evidence-old/`.
- **Submodules:** smom-dbis-138/docs, etc. — out of scope for this plan; see [11-references/SUBMODULE_RELATIONSHIP_MAP.md](../11-references/SUBMODULE_RELATIONSHIP_MAP.md).
---
## 2. 00-meta Classification
### Keep (canonical / living)
| Document | Role |
|----------|------|
| **NEXT_STEPS_INDEX.md** | Single entry for "what to do next" → links to FOR_YOU, OPERATOR, REMAINING_WORK_DETAILED_STEPS, etc. |
| **NEXT_STEPS_MASTER.md** | Master list of next steps |
| **NEXT_STEPS_FOR_YOU.md** | Your personal checklist (Ledger, from-anywhere) |
| **NEXT_STEPS_OPERATOR.md** | Operator runbook (LAN/creds) |
| **NEXT_STEPS_ALL.md** | Consolidated all-audience next steps |
| **REMAINING_WORK_DETAILED_STEPS.md** | Step-by-step for each remaining task |
| **NEXT_STEPS_AND_REMAINING_TODOS.md** | Full consolidated checklist |
| **TODOS_CONSOLIDATED.md** | Single-file task list (high/medium/LAN/low) |
| **TODO_TASK_LIST_MASTER.md** | Master task list |
| **REMAINING_TASKS_AND_API_FEATURES.md** | Remaining tasks + API inventory |
| **REMAINING_TASKS_NEXT_STEPS_PHASES_REVIEW.md** | Phases review |
| **MASTER_PLAN.md** | Single Master Plan (gaps, phases) |
| **COMPLETION_MASTER_PLAN.md** | Incomplete + missing items; Phase 0–8 |
| **BLITZKRIEG_SUPER_PRO_MAX_MASTER_PLAN.md** | Token/bridge rollout (canonical) |
| **BLITZKRIEG_SOURCE_DOCUMENT_INDEX.md** | Where to update when completed |
| **ALL_REQUIREMENTS.md** | All requirements |
| **ARCHIVE_CANDIDATES.md** | What to archive; consolidation log |
| **DOCUMENTATION_STYLE_GUIDE.md** | Doc standards |
| **DOCUMENTATION_FIX_TASK_LIST.md** | Doc fix tasks + completed fixes |
| **DOCUMENTATION_ENHANCEMENTS_RECOMMENDATIONS.md** | Enhancement recommendations |
| **DOCUMENTATION_QUALITY_REVIEW.md** | Quality review |
| **DOCUMENT_RELATIONSHIP_MAP.md** | Doc relationship diagram (Mermaid/ASCII) |
| **FULL_PARALLEL_EXECUTION_ORDER.md** | Wave 0–3 execution order |
| **WAVE1_COMPLETION_SUMMARY.md** | Wave 1 status |
| **WAVE2_WAVE3_OPERATOR_CHECKLIST.md** | Wave 2/3 checklist |
| **PLACEHOLDERS_AND_REQUIRED_ADDITIONS_LIST.md** | Placeholders, env, API keys |
| **E2E_COMPLETION_TASKS_DETAILED_LIST.md** | E2E tasks by part |
| **REMAINING_WORK_DETAILED_TASKS.md** | Detailed remaining tasks |
| **STEPS_FROM_PROXMOX_OR_LAN_WITH_SECRETS.md** | Steps from Proxmox/LAN |
| **DEPLOY_CONFIRM_AND_FULL_E2E_RUNBOOK.md** | Deploy + E2E runbook |
| **502_DEEP_DIVE_ROOT_CAUSES_AND_FIXES.md** | 502 root cause (operational reference) |
| **UNBLOCK_MAINNET_RPC_403.md** | Mainnet RPC 403 unblock (operational) |
| **MAJOR_UPGRADE_HOLD_OFF.md** | Upgrade hold (decision) |
| **SAFE_PACKAGES_MIGRATION_PLAN.md** | Package migration |
| **MAINTENANCE_SCRIPTS_REVIEW.md** | Maintenance scripts reference |
| **CONTRIBUTOR_GUIDELINES.md** | Contributor guidelines |
| **MARKDOWN_FILE_MAINTENANCE_GUIDE.md** | Markdown maintenance |
### Archive (one-off status / dated reviews)
Moved to `docs/archive/00-meta-pruned/` in 2026-02-20 batch:
| Document | Reason |
|----------|--------|
| COMPLETION_STATUS_20260215.md | Dated completion snapshot; current status in NEXT_STEPS_OPERATOR / REMAINING_WORK_DETAILED_STEPS |
| MASTER_DOCUMENTATION_REVIEW_20260205.md | Dated review; current state in DOCUMENTATION_FIX_TASK_LIST and MASTER_INDEX |
| DOCUMENTATION_REVIEW_20260216.md | Dated review; decisions captured in ARCHIVE_CANDIDATES and this plan |
| DOCUMENTATION_REVIEW_CONTINUED_20260216.md | Dated continued review |
| COMPREHENSIVE_DOCUMENTATION_REVIEW_2026-01-31.md | Dated comprehensive review |
| DOCUMENTATION_UPGRADE_SUMMARY.md | One-off upgrade summary |
| DOCUMENTATION_REVIEW.md | Generic review; superseded by dated reviews and FIX_TASK_LIST |
| DOCUMENTATION_METRICS.md | One-off metrics; optional future link-check only |
| DOCUMENTATION_RELATIONSHIP_MAP.md | Duplicate of DOCUMENT_RELATIONSHIP_MAP (keep one) |
| JNA_WHY_NOT_WORKING_REVIEW.md | One-off investigation |
| VMID_2101_CHANGES_AND_FAILURES.md | One-off incident; operational fixes in runbooks |
| COMPREHENSIVE_PROJECT_REVIEW.md | One-off project review |
### Review later (possible merge or archive)
| Document | Note |
|----------|------|
| MASTER_DOCUMENTATION_INDEX.md | Overlaps with docs/MASTER_INDEX.md; consider single canonical index at docs/ |
| REMAINING_COMPONENTS_TASKS_AND_RECOMMENDATIONS.md | Overlap with REMAINING_TASKS_*; consider merging into one |
| RECOMMENDATIONS_OPERATOR_CHECKLIST.md | Overlap with 11-references/OPERATOR_OPTIONAL_CHECKLIST; keep or merge |
| PLACEHOLDERS_AND_COMPLETION_MASTER_LIST.md | Overlap with PLACEHOLDERS_AND_REQUIRED_ADDITIONS_LIST |
| NOT_IMPLEMENTED_FULL_SCOPE.md | Keep; distinct scope doc |
| LEGAL_DOCUMENTS_IMPLEMENTATION.md | Keep or move to compliance/ |
| DBIS_CORE_WHEN_TO_IMPLEMENT.md | Keep; decision doc |
| NETWORK_PLACEHOLDERS_DECISION.md | Keep; decision doc |
| NOT_CHANGED_BY_DESIGN_ACTIONABLE_STEPS.md | Keep; design decisions |
| REMAINING_WORK_BREAKDOWN_AND_ANSWERS.md | Overlap with REMAINING_*; consider merge |
| ALL_TASKS_DETAILED_STEPS.md | Overlap with REMAINING_WORK_DETAILED_STEPS |
| MASTER_TODO_EXPANDED.md | Overlap with TODO_TASK_LIST_MASTER / TODOS_CONSOLIDATED |
| REMAINING_ITEMS_FULL_PARALLEL_LIST.md | Overlap with FULL_PARALLEL_* |
| TASKS_TO_COMPLETE_AND_FIX.md | Overlap with TODOS_CONSOLIDATED |
| CONTINUE_AND_COMPLETE.md | **Archived** (archive/00-meta-pruned, Batch 5) |
| FULL_PARALLEL_RUN_LOG.md | **Archived** (archive/00-meta-pruned, Batch 5) |
| PHASES_AND_TASKS_MASTER.md | Keep; phase checklist |
| PARALLEL_TASK_STRUCTURE.md | Keep; execution structure |
| EXTERNAL_INTEGRATIONS_CHECKLIST.md | Keep |
| API_KEYS_DOTENV_STATUS.md | Keep or merge into MASTER_SECRETS_INVENTORY |
| SCRIPT_INVENTORY.md | Keep; script reference |
---
## 3. Docs root
| Document | Action |
|----------|--------|
| ALL_TASKS_COMPLETE.md | **Moved** to docs/archive/root-status-reports/ (2026-02-20) |
| GAPS_AND_RECOMMENDATIONS_CONSOLIDATED.md | Keep; single reference for gaps/placeholders. Linked from MASTER_INDEX. |
| PLACEHOLDERS_AND_TBD.md | Keep; cross-link with 00-meta/PLACEHOLDERS_* and GAPS_AND_RECOMMENDATIONS |
| REQUIRED_FIXES_UPDATES_GAPS.md | Keep; cross-link with GAPS_AND_RECOMMENDATIONS |
| VAULT_SYSTEM_MASTER_TECHNICAL_PLAN.md | Keep in docs or move to 02-architecture/ |
| INTEGRATION_TEST_SUMMARY.md | Keep or archive if dated |
---
## 3b. Project root (repository root) — cleanup 2026-02-20
**Kept at root:** README.md, PROJECT_STRUCTURE.md, INTEGRATIONS_QUICK_REFERENCE.md, COMPREHENSIVE_STATUS_BRIDGE_READY.md (linked from docs), package.json, pnpm-lock.yaml, pnpm-workspace.yaml, renovate.json, .env.example, claude_desktop_config.json.example, token-list.json, .gitignore, .gitmodules.
**Moved:** 40+ status/completion/temp files and screenshots → [docs/archive/root-cleanup-20260220/](../archive/root-cleanup-20260220/README.md). **fix-wsl-ip.sh** → scripts/fix-wsl-ip.sh.
---
## 4. Verification evidence
- **Policy:** Keep last 2–3 run dates per type (e2e, backend-vms). Older runs → `archive/verification-evidence-old/`.
- **Summary docs** in verification-evidence (e.g. COMPLETION_RUN_*, DO_ALL_*): keep recent; archive old dated summaries to archive/00-meta-pruned or verification-evidence-old.
---
## 5. Eliminating deprecated and inconsistent content
- **Single entry point:** [docs/MASTER_INDEX.md](../MASTER_INDEX.md) — use as the documentation index; it lists canonical sources and a "Deprecated / superseded" table.
- **Recommendations canonical:** [00-meta/ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md](ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md). Do not use [ALL_IMPROVEMENTS_AND_GAPS_INDEX.md](../ALL_IMPROVEMENTS_AND_GAPS_INDEX.md) as primary; it is superseded (stub/redirect only).
- **Contract/address status:** [11-references/ADDRESS_MATRIX_AND_STATUS.md](../11-references/ADDRESS_MATRIX_AND_STATUS.md). CONTRACT_INVENTORY_AND_VERIFICATION and SMART_CONTRACTS_INVENTORY are deleted/superseded.
- **Runbooks:** [03-deployment/OPERATIONAL_RUNBOOKS.md](../03-deployment/OPERATIONAL_RUNBOOKS.md) is the single runbook index. [RUNBOOKS_MASTER_INDEX.md](../RUNBOOKS_MASTER_INDEX.md) is a redirect stub for backward compatibility.
- When adding or updating docs, link to MASTER_INDEX and the canonical doc for that topic; avoid creating new "master" or "index" docs that duplicate existing ones.
---
## 6. Next steps for maintainers
1. Run link check quarterly (MASTER_INDEX, docs/README).
2. Each quarter: move clearly one-off/dated 00-meta docs to archive/00-meta-pruned per this plan.
3. Consider merging REMAINING_* and NEXT_STEPS_* into 2–3 canonical files (entry: NEXT_STEPS_INDEX.md).
4. Add "Last reviewed" to ARCHIVE_CANDIDATES after each consolidation run.
5. **Eliminate deprecated content:** Do not reference ALL_IMPROVEMENTS_AND_GAPS_INDEX, CONTRACT_INVENTORY_AND_VERIFICATION, or SMART_CONTRACTS_INVENTORY as primary sources; use MASTER_INDEX and the canonical docs it points to.
---
**Consolidation run 2026-02-20:** NEXT_STEPS_INDEX.md added; Batch 4 (12 files) archived to 00-meta-pruned; ARCHIVE_CANDIDATES and MASTER_INDEX updated. **Follow-up:** Batch 5 (CONTINUE_AND_COMPLETE, FULL_PARALLEL_RUN_LOG) → 00-meta-pruned; ALL_TASKS_COMPLETE → root-status-reports; project root cleanup → docs/archive/root-cleanup-20260220; fix-wsl-ip.sh → scripts/.
**Consolidation run 2026-03-02:** docs/MASTER_INDEX.md and docs/README.md created; docs/RUNBOOKS_MASTER_INDEX.md added (redirect stub); DOCUMENTATION_CONSOLIDATION_PLAN §5 (eliminating deprecated content) and §6 (maintainers) updated; ARCHIVE_CANDIDATES Last reviewed set to 2026-03-02.
Reference in New Issue View Git Blame Copy Permalink