smom-dbis-138/docs/DOCUMENTATION_QUICK_FIXES.md

# 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