Skip to content

CONSOLIDATION_ACTION_CHECKLIST.md

Latest commit

 

History

History
667 lines (498 loc) · 21.5 KB

CONSOLIDATION_ACTION_CHECKLIST.md

File metadata and controls

667 lines (498 loc) · 21.5 KB

Documentation Consolidation Action Checklist

Date: November 9, 2025 Goal: Execute documentation consolidation in phases over 2 weeks Status: Ready to implement

Pre-Implementation Checklist

  • Review Analysis Document: Read /docs/DOCUMENTATION_CONSOLIDATION_ANALYSIS.md completely
  • Backup Current Structure: Verify git status shows docs/ clean or committed
  • Set Up Tracking: Create a branch for documentation consolidation
  • Review Archive Strategy: Confirm archive organization approach

PHASE 1: Testing Documentation (2 hours)

Effort: Low Risk | 7 files affected | 2-3 hours

Step 1.1: Merge TESTING_GUIDE.md into TESTING.md

  • Open docs/testing/TESTING_GUIDE.md
  • Compare with docs/testing/TESTING.md
  • Identify unique content in TESTING_GUIDE.md
  • Add unique content to TESTING.md (merge sections)
  • Check for content that appears in both - use TESTING.md version
  • Update any references in TESTING.md to acknowledge both sources
  • Delete TESTING_GUIDE.md
  • Test: npm test (verify links work)

Time: 30 minutes

Step 1.2: Consolidate QUICK_REFERENCE.md into TESTING_QUICKSTART.md

  • Open docs/testing/QUICK_REFERENCE.md
  • Open docs/testing/TESTING_QUICKSTART.md
  • Copy command reference section from QUICK_REFERENCE into QUICKSTART
  • Merge "Common Commands" table
  • Delete QUICK_REFERENCE.md
  • Rename TESTING_QUICKSTART.md to QUICK_START_TESTING.md
  • Update table of contents in QUICK_START_TESTING.md

Time: 20 minutes

Step 1.3: Archive Non-Authoritative Files

  • Create docs/archive/testing/ directory (if doesn't exist)
  • Move docs/testing/TESTING_SUMMARY.md → docs/archive/testing/
  • Check: any other summary/complete status files in docs/testing/
  • Move those to archive as well

Time: 15 minutes

Step 1.4: Update Navigation

  • Open docs/README.md
  • Update Testing section to reference:
    • Primary: docs/testing/TESTING.md
    • Quick Start: docs/testing/QUICK_START_TESTING.md
    • Strategy: docs/testing/TEST_STRATEGY.md
  • Open docs/INDEX.md
  • Update Testing index entry (if exists)
  • Check any cross-references from other docs to deleted files
  • Run global search for "TESTING_GUIDE.md", "QUICK_REFERENCE.md" (from testing/)
  • Update any found references

Time: 45 minutes

Step 1.5: Verification

  • Run: npm test (ensure test suite still passes)
  • Check: All links in docs/testing/ resolve correctly
  • Verify: docs/README.md links work
  • Git diff: Review what changed

Time: 10 minutes

Files Deleted: 3 (TESTING_GUIDE.md, QUICK_REFERENCE.md, TESTING_SUMMARY.md archived) Files Created: 0 Files Renamed: 1 (TESTING_QUICKSTART.md → QUICK_START_TESTING.md) Files Modified: 3 (TESTING.md, QUICK_START_TESTING.md, README.md)

PHASE 2: Stripe Integration Documentation (3 hours)

Effort: Medium Risk | 12 files affected | 3-4 hours

Step 2.1: Establish Canonical Source

  • Verify docs/integrations/STRIPE_INTEGRATION.md exists
  • Review it contains:
    • Architecture Overview
    • Implementation Details
    • Environment Configuration
    • API Endpoints
    • Database Schema
    • Testing section
    • Troubleshooting
    • Security Considerations

Time: 15 minutes

Step 2.2: Create QUICK_START_STRIPE.md

  • Create new file: docs/billing/QUICK_START_STRIPE.md
  • Include content from:
    • docs/billing/STRIPE_SETUP_COMPLETE.md (setup steps)
    • docs/billing/STRIPE_CONFIGURATION_GUIDE.md (config steps)
    • docs/billing/STRIPE_PRICING_SETUP.md (pricing config)
  • Structure: 
    1. Prerequisites
2. Quick Setup (5 min)
3. Configuration Checklist
4. Verification Steps
5. Next Steps
  • Test: Document is 2-3 pages max (quick reference)

Time: 60 minutes

Step 2.3: Create Payment System Architecture Doc

  • Create: docs/billing/payment-system/PAYMENT_SYSTEM_ARCHITECTURE.md
  • Merge content from:
    • PAYMENT_FLOW_ANALYSIS.md
    • PAYMENT_SYSTEM_FIXES_SUMMARY.md
    • PHASE_2_IDEMPOTENCY_COMPLETE.md (architecture only, not status)
    • PHASE_3_ATOMIC_OPERATIONS_COMPLETE.md (architecture only)
  • Structure: 
    1. System Architecture
2. Payment Flow Diagram
3. Idempotency Implementation
4. Atomic Operations
5. Error Handling
6. Verification

Time: 45 minutes

Step 2.4: Archive Outdated Files

  • Create: docs/archive/billing/ (if doesn't exist)
  • Move these files to archive:
    • docs/billing/STRIPE_SETUP_COMPLETE.md
    • docs/billing/STRIPE_CONFIGURATION_GUIDE.md
    • docs/billing/STRIPE_PRICING_SETUP.md
    • docs/billing/STRIPE_PRICING_IMPLEMENTATION_COMPLETE.md
    • docs/billing/BILLING_AUDIT_COMPLETE.md
    • docs/billing/payment-system/PHASE_2_IDEMPOTENCY_COMPLETE.md
    • docs/billing/payment-system/PHASE_3_ATOMIC_OPERATIONS_COMPLETE.md

Time: 15 minutes

Step 2.5: Verify Secondary Files

  • Keep: docs/billing/ADVERTISING_STRIPE_SETUP.md (advertising-specific)
  • Keep: docs/integrations/STRIPE_INTEGRATION.md (canonical)
  • Keep: docs/integrations/STRIPE_DASHBOARD_AUDIT_REPORT.md
  • Keep: docs/audits/STRIPE_FUNCTIONALITY_AUDIT_LAW_PROFESSIONAL_PERSPECTIVE.md
  • Delete: Any other Stripe status files not listed

Time: 10 minutes

Step 2.6: Update Navigation

  • Update: docs/README.md
    • Reference QUICK_START_STRIPE.md for quick setup
    • Reference docs/integrations/STRIPE_INTEGRATION.md for full guide
  • Update: docs/billing/README.md (create if doesn't exist)
    • Index of all billing/stripe docs
  • Search for any old file references in docs/
  • Update cross-references

Time: 30 minutes

Step 2.7: Verification

  • Confirm all links in updated docs work
  • Check: STRIPE_INTEGRATION.md still complete and accurate
  • Check: QUICK_START_STRIPE.md is quick (not >5 pages)
  • Review: Payment system architecture clarity
  • Git diff: Verify changes

Time: 15 minutes

Files Deleted: 7 (archived to docs/archive/billing/) Files Created: 2 (QUICK_START_STRIPE.md, PAYMENT_SYSTEM_ARCHITECTURE.md) Files Renamed: 0 Files Modified: 3 (STRIPE_INTEGRATION.md, README.md, billing/README.md)

PHASE 3: Migration Documentation (4 hours)

Effort: Medium-High Risk | 30+ files affected | 4-5 hours

Step 3.1: Create New Directory Structure

  • Create: docs/database/migration-guides/feature-migrations/
  • Verify exists: docs/database/migration-guides/ parent directory
  • Create: docs/archive/migrations/ (for old migration docs)

Time: 10 minutes

Step 3.2: Create Consolidated MIGRATION_GUIDE.md

  • Create: docs/database/migration-guides/MIGRATION_GUIDE.md
  • Merge content from these files in /docs/migrations/:
    • MIGRATION_INSTRUCTIONS.md
    • MIGRATION_SETUP.md
    • MIGRATION_RUNBOOK.md
  • Include sections: 
    1. Prerequisites
2. Environment Setup
3. Step-by-Step Execution
4. Verification
5. Rollback Procedures
6. Troubleshooting
  • Test: Structure is clear and follows single-source-of-truth

Time: 90 minutes

Step 3.3: Create Consolidated QUICK_START_MIGRATION.md

  • Create: docs/database/migration-guides/QUICK_START_MIGRATION.md
  • Merge from:
    • /docs/migrations/MIGRATION_QUICK_START.md
    • /docs/database/migration-guides/QUICK_START_TRIGRAM.md
  • Must cover:
    • Quick 5-min setup
    • Most common migrations
    • Basic verification
  • Test: Keep under 3 pages

Time: 45 minutes

Step 3.4: Create SAFETY_CHECKLIST.md

  • Create: docs/database/migration-guides/SAFETY_CHECKLIST.md
  • Merge from:
    • /docs/migrations/MIGRATION_SAFETY.md
    • /docs/migrations/MIGRATION_SAFETY_CHECKLIST.md
    • /docs/migrations/MIGRATION_TROUBLESHOOTING.md
  • Include:
    • Pre-migration checks
    • During migration monitoring
    • Post-migration verification
    • Common issues & solutions

Time: 60 minutes

Step 3.5: Consolidate Feature-Specific Migrations

  • Create: docs/database/migration-guides/feature-migrations/TRIGRAM_INDEXES.md
    • Merge: README_TRIGRAM_INDEXES.md, QUICK_START_TRIGRAM.md
  • Create: docs/database/migration-guides/feature-migrations/COMMERCE_MIGRATION.md
    • Move: COMMERCE_MIGRATION_GUIDE.md content
  • Create: docs/database/migration-guides/feature-migrations/ELECTION_SCHEMA.md
    • Move: ELECTION_SCHEMA_GUIDE.md, ELECTION_SCHEMA_README.md, ELECTION_TESTING_GUIDE.md
  • Create: docs/database/migration-guides/feature-migrations/ANALYTICS_INDEXES.md
    • Move: ANALYTICS_INDEX_GUIDE.md content

Time: 90 minutes

Step 3.6: Archive Status/Report Files

  • Move to docs/archive/migrations/:
    • MIGRATION_STATUS_REPORT.md
    • MIGRATION_STATUS_REPORT_v2.md
    • MIGRATION_COMPLETION_REPORT.md
    • MIGRATION_SUCCESS_REPORT.md
    • MIGRATION_DEBUG_REPORT.md
    • CASE_ANALYTICS_INDEX_REPORT.md
    • COURTS_UNIQUE_CONSTRAINT_MIGRATION_REPORT.md
    • MIGRATION_SUMMARY.txt
    • MIGRATION_TEST_PLAN.md

Time: 20 minutes

Step 3.7: Update Primary README

  • Update/Create: docs/database/migration-guides/README.md
    • Overview of migration documentation
    • Links to all consolidated guides
    • Quick start section
    • Safety checklist link
    • Feature-specific migration links

Time: 30 minutes

Step 3.8: Decide on docs/migrations/

  • Option A (Recommended): Archive entire directory 
    Move docs/migrations/ → docs/archive/migrations/
Create index file in archive explaining this is historical
  • Option B: Keep as redirect 
    Keep docs/migrations/README.md with index
Add note: "Consolidated docs moved to docs/database/migration-guides/"
Delete all other files

Decision: [ ] Option A or [ ] Option B

Time: 30 minutes

Step 3.9: Update Navigation

  • Update: docs/README.md (Migration section)
    • Point to docs/database/migration-guides/
  • Update: docs/database/README.md (if exists) or create
    • Include migration guides section
  • Search project for references to /docs/migrations/
  • Update any found references to new location
  • Update: docs/INDEX.md (migrations section)

Time: 45 minutes

Step 3.10: Verification

  • Check all new files are readable and well-structured
  • Verify no duplicate content between consolidated files
  • Test: All links work
  • Confirm: No stale references in docs/
  • Git diff: Review all changes

Time: 30 minutes

Files Deleted/Archived: 20+ (moved to docs/archive/migrations/) Files Created: 5-6 consolidated files Files Renamed: 0 Files Modified: 5 (READMEs, INDEX.md)

PHASE 4: Courtlistener Integration (2 hours)

Effort: Low Risk | 8 files affected | 2-3 hours

Step 4.1: Consolidate Schema Documentation

  • Create: docs/integrations/courtlistener/SCHEMA_REFERENCE.md
  • Merge these root-level files:
    • docs/courtlistener-schema-design.md
    • docs/courtlistener-schema-implementation-guide.md
    • docs/courtlistener-schema-quick-reference.md
    • docs/courtlistener-schema-summary.md
  • Structure: 
    1. Schema Overview
2. Table Definitions
3. Relationships
4. Implementation Guide
5. Quick Reference Tables
  • Test: All schema info is present and clear

Time: 60 minutes

Step 4.2: Move Root-Level Courtlistener Files

  • Move: docs/COURTLISTENER_BULK_IMPORT_GUIDE.md → docs/integrations/courtlistener/BULK_IMPORT.md
  • Delete: docs/COURTLISTENER_SYNC_STATUS.md (duplicate of integrations/ version)
  • Verify no other root-level COURTLISTENER_* files exist
  • Check for any root-level CourtListener files not yet moved

Time: 20 minutes

Step 4.3: Create Courtlistener README/Index

  • Create/Update: docs/integrations/courtlistener/README.md
    • Overview of CourtListener integration
    • Links to key guides:
      • Quick Start
      • Integration Guide
      • Schema Reference
      • Retry Implementation
      • Authentication Guide
      • Bulk Import
      • Political Affiliations Sync
      • Sync Guide

Time: 30 minutes

Step 4.4: Archive Root Schema Files

  • Move to: docs/archive/courtlistener/ (create if needed)
    • courtlistener-schema-design.md (old location)
    • courtlistener-schema-implementation-guide.md (old location)
    • courtlistener-schema-quick-reference.md (old location)
    • courtlistener-schema-summary.md (old location)

Time: 10 minutes

Step 4.5: Update Navigation

  • Update: docs/README.md (Integrations section)
    • Link to docs/integrations/courtlistener/
  • Update: docs/integrations/README.md (if exists) or create
    • Include CourtListener docs section
  • Search for references to deleted files
  • Update: docs/INDEX.md (integrations section)

Time: 30 minutes

Step 4.6: Verification

  • Confirm all files in courtlistener/ directory are consistent
  • Check: README.md provides clear navigation
  • Test: All links work
  • Verify: No broken references from other docs
  • Git diff: Review changes

Time: 20 minutes

Files Deleted/Archived: 4 (root schema files) Files Created: 2 (SCHEMA_REFERENCE.md, README.md) Files Modified: 1 (BULK_IMPORT.md - moved) Files Renamed: 1 (BULK_IMPORT_GUIDE.md → BULK_IMPORT.md)

PHASE 5: README Standardization (1 hour)

Effort: Low Risk | 5+ README files | 1-2 hours

Step 5.1: Audit Current READMEs

  • List all README.md files:
    • docs/README.md (PRIMARY)
    • docs/INDEX.md (SECONDARY)
    • docs/testing/README.md (if exists)
    • docs/billing/README.md (if exists)
    • docs/database/README.md (if exists)
    • docs/integrations/README.md (if exists)
    • others?

Time: 15 minutes

Step 5.2: Establish README Strategy

For each folder:

  • PRIMARY folders get README.md (entry point)
    • testing
    • billing
    • integrations
    • database/migration-guides
  • SECONDARY folders get INDEX.md (detailed listing)
    • database
    • deployment
    • others with many subdocs

Time: 15 minutes

Step 5.3: Create Missing READMEs

  • Create: docs/testing/README.md (if missing)
  • Create: docs/billing/README.md (if missing)
  • Create: docs/database/migration-guides/README.md (already done in Phase 3)
  • Create: docs/integrations/README.md (if missing)
  • Update: docs/integrations/courtlistener/README.md (already done in Phase 4)

Each should include:

  • Overview of domain
  • Quick links to key docs
  • Guide to organization

Time: 45 minutes

Step 5.4: Consolidate Duplicate Entry Points

  • Check docs/README.md and docs/INDEX.md
    • docs/README.md = High-level entry (keep)
    • docs/INDEX.md = Detailed navigation (keep)
    • Both should complement, not duplicate
  • Update docs/README.md section: "For detailed listing, see docs/INDEX.md"

Time: 15 minutes

Step 5.5: Update Main README.md

  • Update: docs/README.md
    • Add note about new consolidated structure
    • Update all domain links to new locations
    • Ensure all sections reference correct files
    • Test: All links work

Time: 30 minutes

Files Created: 3-4 READMEs Files Modified: 2 (docs/README.md, docs/INDEX.md)

Final Verification Checklist

After all phases complete:

  • Link Verification: Search docs/ for broken references

    # Check for references to deleted files (examples):
grep -r "TESTING_GUIDE.md" docs/
grep -r "STRIPE_SETUP_COMPLETE.md" docs/
grep -r "MIGRATION_INSTRUCTIONS.md" docs/

  • Directory Structure: Verify new organization

    • docs/database/migration-guides/feature-migrations/ exists
    • docs/archive/ properly organized with subdirectories
    • All major domains have README.md

  • Navigation: Test user flows

    • Starting from docs/README.md, can find all key docs
    • Folder READMEs link back to parent
    • INDEX.md is comprehensive and accurate

  • Git Status: Review changes

    git status
git diff docs/

  • Testing: Run test suite

    npm test

  • Archive Organization: Verify

    • docs/archive/ is well-organized
    • Old docs clearly marked as historical
    • Archive has README explaining contents

  • Documentation Quality: Check

    • No orphaned or incomplete files
    • Consistent formatting across consolidated docs
    • All file names follow conventions (QUICKSTART_, __GUIDE.md)
    • Consolidated files are complete (no content loss)

  • Cross-References: Verify

    • docs/README.md reflects new structure
    • docs/INDEX.md updated with new locations
    • Folder READMEs created for key domains
    • All interdomain links work

File Tracking Sheet

Phase 1: Testing (Target 2-3 hours)

File Action Status Time
TESTING_GUIDE.md Delete/Archive [ ] [ ]
QUICK_REFERENCE.md Delete/Archive [ ] [ ]
TESTING_SUMMARY.md Archive [ ] [ ]
TESTING.md Merge (TESTING_GUIDE) [ ] [ ]
QUICK_START_TESTING.md Rename & Merge [ ] [ ]
docs/README.md Update links [ ] [ ]

Phase 1 Total Time: _ hours

Phase 2: Stripe (Target 3-4 hours)

File Action Status Time
STRIPE_SETUP_COMPLETE.md Archive [ ] [ ]
STRIPE_CONFIGURATION_GUIDE.md Archive [ ] [ ]
STRIPE_PRICING_SETUP.md Archive [ ] [ ]
STRIPE_PRICING_IMPLEMENTATION_COMPLETE.md Archive [ ] [ ]
BILLING_AUDIT_COMPLETE.md Archive [ ] [ ]
PHASE_2_IDEMPOTENCY_COMPLETE.md Archive [ ] [ ]
PHASE_3_ATOMIC_OPERATIONS_COMPLETE.md Archive [ ] [ ]
QUICK_START_STRIPE.md Create [ ] [ ]
PAYMENT_SYSTEM_ARCHITECTURE.md Create [ ] [ ]
docs/README.md Update links [ ] [ ]

Phase 2 Total Time: _ hours

Phase 3: Migrations (Target 4-5 hours)

File Action Status Time
MIGRATION_GUIDE.md Create (consolidated) [ ] [ ]
QUICK_START_MIGRATION.md Create (consolidated) [ ] [ ]
SAFETY_CHECKLIST.md Create (consolidated) [ ] [ ]
feature-migrations/TRIGRAM_INDEXES.md Create [ ] [ ]
feature-migrations/COMMERCE_MIGRATION.md Create [ ] [ ]
feature-migrations/ELECTION_SCHEMA.md Create [ ] [ ]
feature-migrations/ANALYTICS_INDEXES.md Create [ ] [ ]
docs/migrations/ Archive or Index [ ] [ ]
Multiple status files Archive [ ] [ ]
docs/README.md Update links [ ] [ ]

Phase 3 Total Time: _ hours

Phase 4: Courtlistener (Target 2-3 hours)

File Action Status Time
SCHEMA_REFERENCE.md Create (4 files merged) [ ] [ ]
COURTLISTENER_BULK_IMPORT_GUIDE.md Move & Rename [ ] [ ]
COURTLISTENER_SYNC_STATUS.md (root) Delete [ ] [ ]
courtlistener-schema-*.md (4 files) Archive [ ] [ ]
courtlistener/README.md Create/Update [ ] [ ]
docs/README.md Update links [ ] [ ]

Phase 4 Total Time: _ hours

Phase 5: README Standardization (Target 1-2 hours)

File Action Status Time
docs/testing/README.md Create [ ] [ ]
docs/billing/README.md Create [ ] [ ]
docs/integrations/README.md Create [ ] [ ]
docs/database/migration-guides/README.md Already done [x] -
docs/README.md Update [ ] [ ]
docs/INDEX.md Update [ ] [ ]

Phase 5 Total Time: _ hours

Final Summary

Total Files Affected: 60+ Total Files Deleted: 20+ (archived) Total Files Created: 15+ Total Files Modified: 20+ Estimated Total Time: 12-16 hours (spread over 2 weeks)

Success Criteria:

  • All listed files processed
  • No broken internal links
  • Archive organized and documented
  • New consolidated files complete and accurate
  • Navigation READMEs created
  • docs/README.md updated and accurate
  • All changes committed to git with clear messages

Next Step: Begin Phase 1 by creating a git branch for documentation consolidation