Archive legacy status docs and canonicalize genesis entrypoints
This commit is contained in:
defiQUG
@@ -4,6 +4,8 @@
|
||||
**Reviewer**: Auto (AI Assistant)
|
||||
**Scope**: Complete review of `/docs/` directory (621+ files)
|
||||
|
||||
**Current Note (2026-04-12)**: This file is retained as the original audit baseline. The largest structural issue it identified, the oversized status-report surface, has since been cleaned up: active navigation now goes through `docs/operations/status-reports/STATUS_REPORTS_INDEX.md`, and historical reports live under `docs/archive/status-reports/`.
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
@@ -13,11 +15,11 @@ This document provides a comprehensive review of all documentation in the `docs/
|
||||
### Key Findings
|
||||
|
||||
- **Total Documentation Files**: 621+ markdown files
|
||||
- **Status Reports**: 90+ files in `operations/status-reports/` (many may be outdated)
|
||||
- **Index Files**: 3 different index files with overlapping content
|
||||
- **Configuration Guides**: 3 similar guides that could be consolidated
|
||||
- **Status Reports**: The legacy 90+ file pile from `operations/status-reports/` has been archived; active status navigation now uses `operations/status-reports/STATUS_REPORTS_INDEX.md`
|
||||
- **Index Files**: `MASTER_DOCUMENTATION_INDEX.md` is now the primary index, with `README.md` and `DOCUMENTATION_INDEX.md` acting as entry points
|
||||
- **Configuration Guides**: The similarly named setup guides were renamed and clarified
|
||||
- **Deployment Guides**: 40+ deployment-related files with significant overlap
|
||||
- **Architecture Docs**: 1 file still references IBFT 2.0 instead of QBFT
|
||||
- **Architecture Docs**: The active architecture guide now uses QBFT wording instead of the older IBFT 2.0 phrasing found during the original audit
|
||||
|
||||
---
|
||||
|
||||
@@ -27,17 +29,19 @@ This document provides a comprehensive review of all documentation in the `docs/
|
||||
|
||||
**Location**: `docs/architecture/ARCHITECTURE.md`
|
||||
|
||||
**Issue**: Line 5 states "built on Hyperledger Besu with IBFT 2.0 consensus" but the project has migrated to QBFT.
|
||||
**Current Status**: Resolved in the active architecture guide.
|
||||
|
||||
**Impact**: High - Misleading information for new users and developers
|
||||
**Historical Issue**: The original review found IBFT 2.0 wording in the architecture overview before the project documentation was updated to QBFT terminology.
|
||||
|
||||
**Impact**: Was high because it could mislead new users and developers.
|
||||
|
||||
**Recommendation**:
|
||||
- Update line 5 to reference QBFT instead of IBFT 2.0
|
||||
- Update line 33-34 to reflect QBFT protocol details
|
||||
- Verify all consensus-related references in this file
|
||||
- Keep the active architecture guide on QBFT wording
|
||||
- Treat any remaining IBFT references in historical docs as archive-only context
|
||||
- Verify consensus wording when promoting archived content back into the active surface
|
||||
|
||||
**Files to Update**:
|
||||
- `docs/architecture/ARCHITECTURE.md` (lines 5, 33-34, 45)
|
||||
- Active file already updated: `docs/architecture/ARCHITECTURE.md`
|
||||
|
||||
### 2. Multiple Conflicting Index Files
|
||||
|
||||
@@ -46,16 +50,17 @@ This document provides a comprehensive review of all documentation in the `docs/
|
||||
- `docs/DOCUMENTATION_INDEX.md`
|
||||
- `docs/MASTER_DOCUMENTATION_INDEX.md`
|
||||
|
||||
**Issue**: Three different index files with overlapping but not identical content. This creates confusion about which is the "source of truth."
|
||||
**Current Status**: Mostly resolved.
|
||||
|
||||
**Issue**: The review found three different index files with overlapping but not identical content, which created confusion about the "source of truth."
|
||||
|
||||
**Impact**: High - Users don't know which index to use
|
||||
|
||||
**Recommendation**:
|
||||
- **Consolidate into single master index**: Keep `MASTER_DOCUMENTATION_INDEX.md` as the primary index
|
||||
- **Update README.md**: Make it a simple entry point that links to the master index
|
||||
- **Archive or merge DOCUMENTATION_INDEX.md**: Either merge its unique content into the master index or archive it
|
||||
- **Add "Last Updated" dates** to all index files
|
||||
- **Cross-reference** between files if keeping multiple
|
||||
- Keep `MASTER_DOCUMENTATION_INDEX.md` as the primary index
|
||||
- Keep `README.md` and `DOCUMENTATION_INDEX.md` as lightweight entry points that route readers to the master index
|
||||
- Maintain "Last Updated" dates on the index files
|
||||
- Repoint links promptly when archive moves happen
|
||||
|
||||
### 3. Duplicate Configuration Guides
|
||||
|
||||
@@ -64,18 +69,19 @@ This document provides a comprehensive review of all documentation in the `docs/
|
||||
- `ENV_SETUP.md` - Environment variables setup (Azure/Cloudflare focused)
|
||||
- `ENVIRONMENT_SETUP.md` - Contract deployment environment setup
|
||||
|
||||
**Issue**: Three guides with overlapping but distinct purposes. Names are confusingly similar.
|
||||
**Current Status**: Resolved in the active docs.
|
||||
|
||||
**Issue**: The original guide names were confusingly similar even though the files served different purposes.
|
||||
|
||||
**Impact**: Medium-High - Users may not know which guide to follow
|
||||
|
||||
**Recommendation**:
|
||||
- **Rename for clarity**:
|
||||
- Keep the clearer filenames in place:
|
||||
- `CONFIGURATION_GUIDE.md` → `NETWORK_CONFIGURATION_GUIDE.md`
|
||||
- `ENV_SETUP.md` → `AZURE_CLOUDFLARE_ENV_SETUP.md`
|
||||
- `ENVIRONMENT_SETUP.md` → `CONTRACT_DEPLOYMENT_ENV_SETUP.md`
|
||||
- **Add clear purpose statements** at the top of each file
|
||||
- **Cross-reference** between related guides
|
||||
- **Create a configuration index** that explains when to use each guide
|
||||
- Keep purpose statements and cross-references near the top of each file
|
||||
- Use `configuration/CONFIGURATION_INDEX.md` as the routing entry point
|
||||
|
||||
### 4. Duplicate Naming Convention Files
|
||||
|
||||
@@ -83,39 +89,42 @@ This document provides a comprehensive review of all documentation in the `docs/
|
||||
- `NAMING_CONVENTION.md`
|
||||
- `NAMING_CONVENTIONS.md`
|
||||
|
||||
**Issue**: Two files with nearly identical names - likely duplicates or one is outdated.
|
||||
**Current Status**: Resolved in the active docs.
|
||||
|
||||
**Issue**: Two files with nearly identical names created uncertainty about which convention was authoritative.
|
||||
|
||||
**Impact**: Medium - Confusion about which file to reference
|
||||
|
||||
**Recommendation**:
|
||||
- **Compare both files** to identify differences
|
||||
- **Consolidate** if duplicates, or **rename** if they serve different purposes
|
||||
- **Update all references** to use the correct filename
|
||||
- Keep the explicit split between:
|
||||
- `AZURE_NAMING_CONVENTION_2CHAR.md`
|
||||
- `AZURE_NAMING_CONVENTION_3CHAR.md`
|
||||
- Preserve cross-references between the two conventions
|
||||
- Update links if additional naming docs are introduced
|
||||
|
||||
---
|
||||
|
||||
## 🟠 High Priority Issues (Should Fix Soon)
|
||||
|
||||
### 5. Excessive Status Reports (90+ Files)
|
||||
### 5. Excessive Status Reports (Resolved 2026-04-12)
|
||||
|
||||
**Location**: `docs/operations/status-reports/`
|
||||
**Current Location**:
|
||||
- Active navigation: `docs/operations/status-reports/STATUS_REPORTS_INDEX.md`
|
||||
- Historical collections: `docs/archive/status-reports/`
|
||||
|
||||
**Issue**: 90+ status report files, many likely outdated or redundant. Examples:
|
||||
- Multiple "COMPLETE" reports: `COMPLETE_ALL_TASKS_SUMMARY.md`, `COMPLETE_DEPLOYMENT_STATUS.md`, `COMPLETE_ENTERPRISE_TASK_SUMMARY.md`, `COMPLETE_NEXT_STEPS_REPORT.md`, `COMPLETE_TASK_SUMMARY.md`
|
||||
- Multiple "FINAL" reports: `FINAL_COMPLETE_REPORT.md`, `FINAL_COMPLETE_STATUS.md`, `FINAL_COMPLETION_REPORT.md`, `FINAL_COMPLETION_STATUS.md`, `FINAL_DEPLOYMENT_STATUS.md`, `FINAL_PROJECT_STATUS.md`, `FINAL_SUMMARY.md`
|
||||
- Multiple "TODO" reports: `TODO_COMPLETE_SUMMARY.md`, `TODO_COMPLETION_SUMMARY.md`, `TODO_STATUS_REPORT.md`
|
||||
**Historical Issue**: The review originally found 90+ status report files in `docs/operations/status-reports/`, including multiple overlapping "COMPLETE", "FINAL", and "TODO" summaries.
|
||||
|
||||
**Impact**: High - Difficult to find current status, many outdated reports
|
||||
**Impact**: High at the time because it was difficult to find the current status among redundant historical reports.
|
||||
|
||||
**Recommendation**:
|
||||
- **Create status report retention policy**: Archive reports older than 6 months
|
||||
- **Consolidate similar reports**: Merge multiple "COMPLETE" or "FINAL" reports into single documents
|
||||
- **Create a status report index**: `STATUS_REPORTS_INDEX.md` that categorizes reports by:
|
||||
- Date range
|
||||
- Topic (deployment, infrastructure, tasks, etc.)
|
||||
- Status (current vs. historical)
|
||||
- **Archive old reports**: Move reports older than 6 months to `docs/archive/status-reports/`
|
||||
- **Create a "Current Status" document**: Single source of truth for current project status
|
||||
**Current Outcome**:
|
||||
- Legacy report piles from `docs/operations/status-reports/`, `docs/`, and the repository root were archived into dedicated collections under `docs/archive/status-reports/`
|
||||
- `STATUS_REPORTS_INDEX.md` now routes readers to current status docs versus historical archives
|
||||
- Current status tracking now points to active deployment, routing, compile, and task documents instead of the older report pile
|
||||
|
||||
**Maintenance Guidance**:
|
||||
- Keep `docs/operations/status-reports/` limited to active routing/index content
|
||||
- Move narrative completion snapshots and superseded reports into `docs/archive/status-reports/`
|
||||
- Update central indexes whenever new archival moves happen
|
||||
|
||||
### 6. Deployment Guide Proliferation (40+ Files)
|
||||
|
||||
@@ -465,8 +474,8 @@ This document provides a comprehensive review of all documentation in the `docs/
|
||||
|
||||
- [Documentation Index](DOCUMENTATION_INDEX.md)
|
||||
- [Master Documentation Index](MASTER_DOCUMENTATION_INDEX.md)
|
||||
- [Cleanup Complete Summary](CLEANUP_COMPLETE_SUMMARY.md)
|
||||
- [All Recommendations and Suggestions](ALL_RECOMMENDATIONS_AND_SUGGESTIONS.md)
|
||||
- [Cleanup Complete Summary (Archived)](archive/status-reports/docs-root-legacy/CLEANUP_COMPLETE_SUMMARY.md)
|
||||
- [All Recommendations and Suggestions (Archived)](archive/status-reports/docs-root-legacy/ALL_RECOMMENDATIONS_AND_SUGGESTIONS.md)
|
||||
|
||||
---
|
||||
|
||||
@@ -482,4 +491,3 @@ This document provides a comprehensive review of all documentation in the `docs/
|
||||
**Last Updated**: 2025-01-27
|
||||
**Next Review**: Quarterly or as needed
|
||||
**Status**: Active Review
|
||||
|
||||
|
||||
Reference in New Issue
Block a user