shopdb/docs/archive/DOCS_CONSOLIDATION_PLAN.md

ShopDB Documentation Consolidation Plan

Created: 2025-12-11 Total Files: 45 markdown files (25 in /docs/, 20 in root) Total Lines: ~19,400 lines

---

Summary

The documentation has grown organically during the Phase 1-3 migration work. Many files are now historical/completed and can be archived. The goal is to have 6-8 essential docs that developers actually need.

---

Proposed Structure

shopdb/
├── CLAUDE.md                    # KEEP - Claude Code instructions
├── TODO.md                      # KEEP - Active task list
│
└── docs/
    ├── README.md                # REWRITE - Main index/getting started
    ├── DEVELOPMENT.md           # MERGE - Dev setup + patterns (from ASP_DEVELOPMENT_GUIDE + STANDARDS)
    ├── DATABASE.md              # NEW - Current schema + common queries
    ├── API.md                   # RENAME - API documentation (from API_ASP_DOCUMENTATION)
    ├── QUICK_REFERENCE.md       # UPDATE - Cheat sheet
    │
    └── archive/                 # NEW - Historical docs
        └── [completed work]

---

Action Plan

1. KEEP AS-IS (Root)

File	Reason
CLAUDE.md	Active - Claude Code instructions
TODO.md	Active - Task tracking

2. KEEP & UPDATE (docs/)

File	Action
README.md	Rewrite as simple getting-started guide
QUICK_REFERENCE.md	Update with current info, trim fat

3. MERGE INTO NEW FILES

→ docs/DEVELOPMENT.md (merge these):

Source File	Lines	Take From
docs/ASP_DEVELOPMENT_GUIDE.md	586	Dev setup, workflow, patterns
docs/STANDARDS.md	1232	Coding standards (trim to essentials)
docs/NESTED_ENTITY_CREATION.md	218	Complex form patterns
CLAUDE_PROJECT_INSTRUCTIONS.md	76	VBScript rules
CLAUDE_REFERENCE.md	198	Code patterns

→ docs/DATABASE.md (merge these):

Source File	Lines	Take From
docs/MIGRATION_STATUS_SUMMARY.md	166	Current architecture
docs/MIGRATION_QUICK_REFERENCE.md	197	Key queries
docs/INVENTORY_COLUMN_MAPPING.md	214	Column reference
MACHINE_QUICK_REFERENCE.md	337	Machine queries

→ docs/API.md (rename/move):

Source File	Lines	Action
API_ASP_DOCUMENTATION.md	827	Move to docs/API.md

4. ARCHIVE (Historical - Completed Work)

Move to docs/archive/:

File	Lines	Reason
docs/DATABASE_MIGRATION_FINAL_DESIGN.md	696	Phase 1 complete
docs/PC_MACHINES_CONSOLIDATION_PLAN.md	780	Phase 2 complete
docs/PHASE3_NETWORK_DEVICES_MIGRATION_PLAN.md	489	Phase 3 complete
docs/DEEP_DIVE_REPORT.md	1153	Outdated - replace with DATABASE.md
docs/COMPLETE_REFACTORING_SUMMARY.md	357	Completed work
docs/MACHINE_RELATIONSHIPS_EXAMPLES.md	342	Merge into DATABASE.md
docs/INFRASTRUCTURE_*.md (4 files)	~1800	Design docs - completed
docs/VENDOR_*.md (2 files)	~996	Refactoring - completed
docs/PRINTER_MAP_MIGRATION_REPORT.md	593	Completed
docs/WARRANTY_MANAGEMENT_DESIGN.md	516	Design doc
docs/NETWORK_DEVICES_UNIFIED_DESIGN.md	740	Design doc

Move to docs/archive/sessions/:

File	Lines	Reason
SESSION_SUMMARY_2025-11-10.md	417	Historical
SESSION_SUMMARY_2025-11-13.md	686	Historical
PHASE2_*.md (3 files)	~1400	Completed work
MACHINE_*.md (4 files)	~1700	Completed work
DISPLAY_PAGES_UPDATE_SUMMARY.md	469	Completed
ADD_EDIT_MACHINE_UPDATES.md	433	Completed
BUG_FIXES_2025-11-14.md	455	Historical
PRINTER_*.md (2 files)	~500	Completed
SCHEMA_COMPARISON_REPORT_2025-11-20.md	291	Historical

5. DELETE (Redundant)

File	Reason
CLAUDE_PROJECT_INSTRUCTIONS.md	Merged into DEVELOPMENT.md
CLAUDE_REFERENCE.md	Merged into DEVELOPMENT.md + DATABASE.md

---

Final Result

Essential Docs (6 files):

docs/
├── README.md              (~100 lines) - Getting started, links
├── DEVELOPMENT.md         (~400 lines) - Setup, standards, patterns
├── DATABASE.md            (~300 lines) - Schema, queries, architecture
├── API.md                 (~500 lines) - API endpoints
├── QUICK_REFERENCE.md     (~200 lines) - Cheat sheet
└── archive/               - Historical docs (for reference)

Root Files (2 files):

shopdb/
├── CLAUDE.md              - Claude Code instructions
└── TODO.md                - Active tasks

---

Style Rules for New Docs

• No emojis - Use text markers instead (e.g., [OK], [FAIL], NOTE:, WARNING:)
• Plain markdown formatting only
• Consistent heading hierarchy

---

Execution Order

1. Create docs/archive/ and docs/archive/sessions/ directories
2. Move historical files to archive
3. Create new docs/DATABASE.md (consolidate schema info)
4. Create new docs/DEVELOPMENT.md (consolidate dev guides)
5. Move API_ASP_DOCUMENTATION.md → docs/API.md
6. Rewrite docs/README.md as simple index
7. Update docs/QUICK_REFERENCE.md
8. Delete redundant files
9. Update CLAUDE.md to reference new structure

---

Space Savings

• Before: 45 files, ~19,400 lines
• After: 8 active files, ~1,500 lines + archive
• Reduction: ~90% in active documentation

---

Ready to execute?