bert.hausmans/cmdb-insight
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
cmdb-insight/docs/DOCUMENTATION-CONSOLIDATION-PLAN.md
Bert Hausmans f4399a8e4e Consolidate documentation and update backend services 
- Reorganize docs into 'Core deployment guides' and 'Setup and configuration' subdirectories
- Consolidate redundant documentation files (ACR, pipelines, deployment guides)
- Add documentation consolidation plan
- Update backend database factory and logger services
- Update migration script and docker-compose configurations
- Add PostgreSQL setup script
2026-01-22 22:45:54 +01:00

7.2 KiB
Raw Permalink Blame History

Documentation Consolidation - Completed ✅

Overview

This document outlines the consolidation work completed to reduce redundancy and improve maintainability.

Status: ✅ COMPLETED

Documents to DELETE (Outdated/Status/One-time)

  1. REFACTOR-PHASE-2B-3-STATUS.md - Implementation complete, historical status
  2. AUTHENTICATION-IMPLEMENTATION-STATUS.md - Implementation complete, historical status
  3. DATABASE-NORMALIZATION-PROPOSAL.md - Proposal, already implemented
  4. DATABASE-DRIVEN-SCHEMA-IMPLEMENTATION-PLAN.md - Planning doc, already implemented
  5. NEXT-STEPS-ACR-CREATED.md - Temporary next steps, now in main guides
  6. AZURE-REGISTRY-BESLISSING.md - Decision doc, decision already made
  7. refactor-plan.md - Old refactor plan, superseded
  8. JIRA-ASSETS-SYNC-REFACTOR-PLAN-2025-01-21 - Old refactor plan, superseded
  9. KEY-VAULT-ACCESS-REQUEST.md - One-time request doc

Documents to MERGE

Deployment Guides → Single Comprehensive Guide

  • KEEP: AZURE-APP-SERVICE-DEPLOYMENT.md (most complete)
  • MERGE INTO IT:
    • DEPLOYMENT-ADVICE.md (analysis/advice section)
    • DEPLOYMENT-NEXT-STEPS.md (next steps section)
    • QUICK-DEPLOYMENT-GUIDE.md (quick start section)
  • KEEP SEPARATE: PRODUCTION-DEPLOYMENT.md (general production best practices)
  • MERGE: AZURE-DEPLOYMENT-SUMMARY.md + AZURE-QUICK-REFERENCE.md → AZURE-QUICK-REFERENCE.md (comprehensive overview)

ACR Documentation → Single Guide

  • KEEP: AZURE-ACR-QUICKSTART.md (rename to AZURE-ACR-SETUP.md)
  • MERGE INTO IT:
    • AZURE-ACR-SHARED-SETUP.md (shared setup section)
    • AZURE-CONTAINER-REGISTRY.md (general info)
    • AZURE-ACR-PRICING.md (pricing section)
    • AZURE-ACR-PERMISSIONS.md (permissions section)
  • DELETE: AZURE-ACR-NAMING-RECOMMENDATION.md, AZURE-ACR-DNL-SCOPE.md (too specific, merge key points)

Pipeline Documentation → Single Guide

  • KEEP: AZURE-PIPELINES-USAGE.md (rename to AZURE-PIPELINES.md)
  • MERGE INTO IT:
    • AZURE-PIPELINE-DEPLOYMENT.md (deployment section)
    • AZURE-PIPELINE-QUICK-REFERENCE.md (quick reference section)
    • AZURE-PIPELINE-MSI-ERROR-FIX.md (troubleshooting section)
    • AZURE-PIPELINE-REPO-TROUBLESHOOTING.md (troubleshooting section)

Database Documentation → Consolidate

  • KEEP: AZURE-POSTGRESQL-SETUP.md (production setup)
  • KEEP: DATABASE-RECOMMENDATION.md (decision guide)
  • KEEP: DATABASE-RESET-GUIDE.md (operational guide)
  • KEEP: LOCAL-POSTGRES-RESET.md (local development)
  • KEEP: LOCAL-DEVELOPMENT-SETUP.md (local setup)
  • MERGE: DATABASE-ACCESS.md → Into LOCAL-DEVELOPMENT-SETUP.md
  • KEEP: DATABASE-TABLES-AUDIT.md (reference)
  • KEEP: NORMALIZED-DATABASE-IMPLEMENTATION-PLAN.md (architecture reference)
  • KEEP: SCHEMA-DISCOVERY-FLOW.md (architecture reference)

Final Structure

Core Guides (Keep)

  • AZURE-APP-SERVICE-DEPLOYMENT.md - Complete deployment guide
  • AZURE-POSTGRESQL-SETUP.md - Database setup
  • AZURE-ACR-SETUP.md - Container registry (merged)
  • AZURE-PIPELINES.md - CI/CD pipelines (merged)
  • AZURE-QUICK-REFERENCE.md - Quick reference (merged)
  • GREEN-FIELD-DEPLOYMENT-GUIDE.md - Green field deployment
  • PRODUCTION-DEPLOYMENT.md - Production best practices
  • LOCAL-DEVELOPMENT-SETUP.md - Local development

Reference Docs (Keep)

  • AZURE-CLI-QUICKSTART.md - Azure CLI commands
  • AZURE-DEVOPS-SETUP.md - Azure DevOps setup
  • AZURE-NEW-SUBSCRIPTION-SETUP.md - New subscription setup
  • AZURE-SERVICE-CONNECTION-* - Service connection docs
  • AZURE-RESOURCES-OVERVIEW.md - Resources overview
  • Database docs (as listed above)
  • cmdb-insight-specificatie.md - Application specification

Operational Docs (Keep)

  • AUTHENTICATION-ENV-VARS.md - Auth configuration
  • DOCKER-COMPOSE-WARNINGS.md - Docker warnings
  • GITEA-DOCKER-REGISTRY.md - Gitea registry (if used)
  • POSTGRESQL-VERSION-UPGRADE.md - Upgrade guide
  • TYPESCRIPT-LOCAL-VS-CI.md - TypeScript differences
  • DATA-INTEGRITY-PLAN.md - Data integrity

✅ Execution Completed

1. ✅ Deleted Outdated/Status Docs (11 files)

  • REFACTOR-PHASE-2B-3-STATUS.md
  • AUTHENTICATION-IMPLEMENTATION-STATUS.md
  • DATABASE-NORMALIZATION-PROPOSAL.md
  • DATABASE-DRIVEN-SCHEMA-IMPLEMENTATION-PLAN.md
  • NEXT-STEPS-ACR-CREATED.md
  • AZURE-REGISTRY-BESLISSING.md
  • refactor-plan.md
  • JIRA-ASSETS-SYNC-REFACTOR-PLAN-2025-01-21
  • KEY-VAULT-ACCESS-REQUEST.md
  • AZURE-ACR-NAMING-RECOMMENDATION.md
  • AZURE-ACR-DNL-SCOPE.md

2. ✅ Merged Deployment Guides (3 → 1)

  • KEPT: AZURE-APP-SERVICE-DEPLOYMENT.md (enhanced with "Why Azure App Service" section)
  • DELETED:
    • DEPLOYMENT-ADVICE.md (merged into AZURE-APP-SERVICE-DEPLOYMENT.md)
    • DEPLOYMENT-NEXT-STEPS.md (merged into AZURE-APP-SERVICE-DEPLOYMENT.md)
    • QUICK-DEPLOYMENT-GUIDE.md (merged into AZURE-APP-SERVICE-DEPLOYMENT.md)

3. ✅ Consolidated ACR Documentation (6 → 1)

  • RENAMED: AZURE-ACR-QUICKSTART.md → AZURE-ACR-SETUP.md
  • ENHANCED: Added sections from:
    • AZURE-ACR-SHARED-SETUP.md (shared setup)
    • AZURE-ACR-PRICING.md (pricing details)
    • AZURE-ACR-PERMISSIONS.md (permissions mode)
    • AZURE-CONTAINER-REGISTRY.md (general info)
  • DELETED: All redundant ACR docs

4. ✅ Consolidated Pipeline Documentation (5 → 1)

  • RENAMED: AZURE-PIPELINES-USAGE.md → AZURE-PIPELINES.md
  • ENHANCED: Added troubleshooting from:
    • AZURE-PIPELINE-DEPLOYMENT.md (deployment section)
    • AZURE-PIPELINE-QUICK-REFERENCE.md (quick reference)
    • AZURE-PIPELINE-MSI-ERROR-FIX.md (MSI error troubleshooting)
    • AZURE-PIPELINE-REPO-TROUBLESHOOTING.md (repository troubleshooting)
  • DELETED: All redundant pipeline docs

5. ✅ Consolidated Database Documentation

  • MERGED: DATABASE-ACCESS.md → LOCAL-DEVELOPMENT-SETUP.md
  • KEPT: All other database docs (they serve different purposes)

6. ✅ Merged Quick References (2 → 1)

  • KEPT: AZURE-QUICK-REFERENCE.md (enhanced with deployment steps)
  • DELETED: AZURE-DEPLOYMENT-SUMMARY.md (merged into AZURE-QUICK-REFERENCE.md)

7. ✅ Updated Cross-References

  • Fixed all broken references to deleted/renamed files
  • Updated links in remaining documentation

📊 Results

Before: 50+ documents
After: ~30 documents
Deleted: 20+ redundant/outdated documents
Merged: 10+ overlapping documents into comprehensive guides

📁 Final Documentation Structure

Core Deployment Guides

  • AZURE-APP-SERVICE-DEPLOYMENT.md - Complete deployment guide
  • AZURE-POSTGRESQL-SETUP.md - Database setup
  • AZURE-ACR-SETUP.md - Container registry
  • AZURE-PIPELINES.md - CI/CD pipelines
  • AZURE-QUICK-REFERENCE.md - Quick reference
  • GREEN-FIELD-DEPLOYMENT-GUIDE.md - Green field deployment
  • PRODUCTION-DEPLOYMENT.md - Production best practices

Setup & Configuration

  • AZURE-NEW-SUBSCRIPTION-SETUP.md - New subscription setup
  • AZURE-DEVOPS-SETUP.md - Azure DevOps setup
  • AZURE-CLI-QUICKSTART.md - Azure CLI commands
  • LOCAL-DEVELOPMENT-SETUP.md - Local development

Reference & Troubleshooting

  • AZURE-SERVICE-CONNECTION-* - Service connection docs
  • AZURE-RESOURCES-OVERVIEW.md - Resources overview
  • Database docs (recommendation, reset, etc.)
  • Architecture docs (schema discovery, normalized database plan)
Reference in New Issue View Git Blame Copy Permalink