116 lines
3.7 KiB
Markdown
116 lines
3.7 KiB
Markdown
# Documentation Quick Fixes - Action Items
|
|
|
|
**Created**: 2025-01-27
|
|
**Priority**: Critical and High Priority Issues Only
|
|
|
|
**Current Note (2026-04-12)**: Several of the structural fixes below have since been completed. The active docs now route status and historical material separately via `docs/operations/status-reports/STATUS_REPORTS_INDEX.md` and `docs/archive/status-reports/`.
|
|
|
|
This document provides a quick reference for the most critical documentation issues that should be addressed immediately.
|
|
|
|
---
|
|
|
|
## 🔴 Critical Fixes (Do First)
|
|
|
|
### 1. Fix IBFT Reference in Architecture Doc
|
|
**File**: `docs/architecture/ARCHITECTURE.md`
|
|
**Current Status**: Completed
|
|
**Result**:
|
|
- Active architecture and network entry points now describe Chain 138 as QBFT-based
|
|
- Remaining IBFT wording is limited to a shrinking set of legacy milestone or audit-style docs that still need review
|
|
|
|
### 2. Consolidate Index Files
|
|
**Files**:
|
|
- `docs/README.md`
|
|
- `docs/DOCUMENTATION_INDEX.md`
|
|
- `docs/MASTER_DOCUMENTATION_INDEX.md`
|
|
|
|
**Action**:
|
|
- Keep `MASTER_DOCUMENTATION_INDEX.md` as primary
|
|
- Update `README.md` to be simple entry point linking to master index
|
|
- Merge unique content from `DOCUMENTATION_INDEX.md` into master, then archive or delete
|
|
|
|
### 3. Fix Duplicate Configuration Guides
|
|
**Files**:
|
|
- `docs/configuration/CONFIGURATION_GUIDE.md`
|
|
- `docs/configuration/ENV_SETUP.md`
|
|
- `docs/configuration/ENVIRONMENT_SETUP.md`
|
|
|
|
**Action**:
|
|
- Rename for clarity:
|
|
- `CONFIGURATION_GUIDE.md` → `NETWORK_CONFIGURATION_GUIDE.md`
|
|
- `ENV_SETUP.md` → `AZURE_CLOUDFLARE_ENV_SETUP.md`
|
|
- `ENVIRONMENT_SETUP.md` → `CONTRACT_DEPLOYMENT_ENV_SETUP.md`
|
|
- Add purpose statements to each
|
|
- Create cross-references
|
|
|
|
### 4. Fix Duplicate Naming Convention Files
|
|
**Files**:
|
|
- `docs/configuration/NAMING_CONVENTION.md`
|
|
- `docs/configuration/NAMING_CONVENTIONS.md`
|
|
|
|
**Action**:
|
|
- Compare both files
|
|
- Consolidate if duplicates
|
|
- Rename if different purposes
|
|
- Update all references
|
|
|
|
---
|
|
|
|
## 🟠 High Priority Fixes (Do Next)
|
|
|
|
### 5. Archive Old Status Reports
|
|
**Current Status**: Completed on 2026-04-12
|
|
|
|
**Result**:
|
|
- Legacy status-report piles were moved into `docs/archive/status-reports/operations-legacy/`, `docs/archive/status-reports/docs-root-legacy/`, and `docs/archive/status-reports/repo-root-legacy/`
|
|
- `docs/operations/status-reports/STATUS_REPORTS_INDEX.md` now routes readers to current status docs versus historical archives
|
|
- The active documentation surface no longer depends on the older 90+ file report pile
|
|
|
|
### 6. Consolidate Deployment Guides
|
|
**Location**: `docs/deployment/` (40+ files)
|
|
|
|
**Action**:
|
|
- Keep `DEPLOYMENT_QUICK_START.md` as entry point
|
|
- Consolidate into `DEPLOYMENT_GUIDE.md` (comprehensive)
|
|
- Archive historical completion/status reports
|
|
- Create deployment index explaining which doc to use
|
|
|
|
### 7. Add Cross-References
|
|
**Action**:
|
|
- Add "Related Documentation" sections to key guides
|
|
- Link related topics inline
|
|
- Create documentation relationship map
|
|
|
|
### 8. Add Metadata Headers
|
|
**Action**:
|
|
- Add to all documentation:
|
|
```markdown
|
|
**Last Updated**: YYYY-MM-DD
|
|
**Version**: X.Y (if applicable)
|
|
**Status**: Active | Deprecated | Archived
|
|
```
|
|
|
|
---
|
|
|
|
## 📋 Quick Checklist
|
|
|
|
- [x] Fix IBFT → QBFT in active architecture docs
|
|
- [x] Consolidate 3 index files into 1 master-led navigation surface
|
|
- [x] Rename 3 configuration guides for clarity
|
|
- [ ] Fix duplicate naming convention files
|
|
- [x] Archive legacy status-report piles and separate active vs. historical routing
|
|
- [ ] Consolidate deployment guides
|
|
- [ ] Add cross-references to key docs
|
|
- [ ] Add metadata headers to all docs
|
|
|
|
---
|
|
|
|
## 📚 See Also
|
|
|
|
For complete details and all recommendations, see:
|
|
- [Documentation Review and Recommendations](DOCUMENTATION_REVIEW_AND_RECOMMENDATIONS.md)
|
|
|
|
---
|
|
|
|
**Last Updated**: 2026-04-12
|