john/tractatus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
tractatus/docs/DOCUMENT_AUDIT_2025-10-11.md
TheFlow 2fc6e0a593 feat: implement documentation reorganization with archives 
Documentation Reorganization (Option A - Full):
- Reduced public docs from 47 to 11 (76% reduction)
- 31 documents archived (project tracking, outdated)
- 5 documents marked confidential (security, payments)
- Clear 3-tier structure: Getting Started, Framework Details, Case Studies

Archives Infrastructure:
- Added visibility: 'archived' | 'public' | 'confidential' | 'internal'
- Added category: 'conceptual' | 'practical' | 'reference' | 'archived' | 'project-tracking'
- Added order field for explicit document ordering (1-11 for public)
- Added archiveNote field for explaining why documents were archived
- New endpoint: GET /api/documents/archived
- New controller method: listArchivedDocuments()
- UI: Archives section (collapsed by default) at bottom of docs list

Public Documentation (11 documents, well-organized):
  1. Architectural Overview (reference)
  2. Core Concepts (conceptual) - needs Phase 5 update
  3. Implementation Guide (practical) - needs MongoDB rewrite
  4. Core Values & Principles (conceptual)
  5. Case Studies (practical)
  6. Business Case Template (practical)
  7. Glossary (reference) - needs Phase 5 terms
  8-11. Recent Case Studies (practical)

Model Updates:
- src/models/Document.model.js: Added visibility, category, order, archiveNote fields
- src/models/Document.model.js: Added listArchived() static method
- Default sort by order (1-999) instead of date

Controller Updates:
- src/controllers/documents.controller.js: Added listArchivedDocuments()
- Filter excludes archived docs from main list by default

Route Updates:
- src/routes/documents.routes.js: Added GET /api/documents/archived

UI Updates:
- public/js/docs-app.js: New category structure (Getting Started, Framework Details, Reference)
- public/js/docs-app.js: Fetches and displays archived documents in collapsed section
- public/js/docs-app.js: Archives show document count badge
- public/js/docs-app.js: Archive notes displayed below archived document links
- Auto-loads Architectural Overview (order: 1) on page load

Scripts Created:
- scripts/archive-outdated-documents.js: Archive 10 outdated documents
- scripts/update-document-metadata.js: Set order/category for 7 core docs
- scripts/archive-all-internal-documents.js: Mass archive 23 internal docs

Documentation:
- docs/DOCUMENT_AUDIT_2025-10-11.md: Comprehensive audit of all 47 documents
- docs/DOCUMENT_REORGANIZATION_SUMMARY.md: Executive summary with before/after

Next Steps (Phase 2 - Content Updates):
- Update Core Concepts for Phase 5 MongoDB architecture
- Rewrite Implementation Guide for MongoDB deployment
- Update Glossary with Phase 5 terms (MongoDB, MemoryProxy, API Memory)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-11 01:26:14 +13:00

10 KiB
Raw Blame History

Tractatus Documentation Audit & Reorganization Plan

Date: 2025-10-11 Purpose: Improve UX by reducing document clutter and ensuring current, accurate information Objective: World-class documentation experience with clear categorization

Current State: 17 Documents (Too Many, Poorly Organized)

Problems Identified:

  1. No categorization: 16/17 documents have category: none
  2. Outdated content: Multiple documents reference pre-Phase 5 architecture
  3. Misleading information: Old architecture docs contradict current implementation
  4. Project tracking clutter: Session summaries visible to public (should be archived)
  5. Poor UX: Visitors overwhelmed with 17 documents, unclear which to read first

Document-by-Document Audit

✅ KEEP - Core Documentation (7 documents → 5 after updates)

1. Architectural Overview & Research Status ✅ PERFECT

  • Status: NEW, v1.0.0, Current as of 2025-10-11
  • Category: reference
  • Audience: general
  • Action: KEEP AS-IS (order: 1)
  • Rationale: Comprehensive, current, production-ready status

2. Core Concepts of the Tractatus Framework ⚠️ NEEDS UPDATE

  • Status: Outdated (references 5 services, now 6)
  • Category: none → should be conceptual
  • Audience: general
  • Action: UPDATE to reflect Phase 5 completion
  • Updates Needed:
    • Add MongoDB persistence layer
    • Add API Memory integration
    • Update service count (5 → 6 with BlogCuration)
    • Reference architectural overview for details
  • New Order: 2

3. Implementation Guide ⚠️ NEEDS MAJOR UPDATE

  • Status: Outdated (filesystem-based, pre-MongoDB)
  • Category: none → should be practical
  • Audience: technical
  • Action: UPDATE to reflect MongoDB architecture
  • Updates Needed:
    • MongoDB setup instructions
    • Remove filesystem references
    • Add environment variables (MONGODB_URI)
    • Update initialization code
    • Add production deployment section
  • New Order: 3

4. Glossary of Terms ⚠️ NEEDS UPDATE

  • Status: Partially outdated
  • Category: none → should be reference
  • Audience: general
  • Action: UPDATE with Phase 5 terms
  • Updates Needed:
    • Add: MongoDB, MemoryProxy, API Memory
    • Update: Persistence mechanisms
    • Add: Hybrid architecture terms
  • New Order: 8 (reference section)

5. Core Values and Principles ✅ KEEP

  • Status: Current (strategic foundation)
  • Category: none → should be conceptual
  • Audience: general
  • Action: KEEP, update metadata only
  • New Order: 4

6. Case Studies - Real-World LLM Failure Modes ✅ KEEP

  • Status: Current (examples remain valid)
  • Category: none → should be practical
  • Audience: general
  • Action: KEEP, update metadata only
  • New Order: 5

7. Business Case Template ✅ KEEP

  • Status: Current (practical tool)
  • Category: none → should be practical
  • Audience: business
  • Action: KEEP, update metadata only
  • New Order: 6

📦 ARCHIVE - Outdated/Misleading (5 documents)

8. Introduction to the Tractatus Framework 📦 ARCHIVE

  • Why Archive: Outdated architecture, contradicts current implementation
  • Problem: References filesystem-only storage, pre-MongoDB
  • Category: none → should be archived
  • Visibility: public → archived
  • Note: "See Architectural Overview for current introduction"

9. Tractatus-Based LLM Architecture for AI Safety 📦 ARCHIVE

  • Why Archive: Pre-Phase 5 architecture, now misleading
  • Problem: Proposes architecture that was later replaced
  • Category: none → should be archived
  • Note: "Historical proposal. See Architectural Overview for implemented architecture."

10. Executive Brief: Tractatus-Based LLM Architecture 📦 ARCHIVE

  • Why Archive: Pre-Phase 5, outdated claims
  • Problem: Based on old architecture
  • Category: none → should be archived
  • Note: "Historical brief. See Architectural Overview for current status."

11. Tractatus Framework Enforcement for Claude Code 📦 ARCHIVE

  • Why Archive: Development-specific, not public documentation
  • Problem: Internal tool documentation, confusing for general audience
  • Category: none → should be archived
  • Audience: technical → developer
  • Note: "Development tool documentation. See Implementation Guide for production deployment."

12. Organizational Theory Foundations ⚠️ MAYBE ARCHIVE

  • Why Consider: Academic, not practical for most visitors
  • Decision: ARCHIVE (can restore if academic audience grows)
  • Category: none → should be archived
  • Note: "Academic foundations. See Core Concepts for practical overview."

📊 ARCHIVE - Project Tracking (5 documents)

These are valuable for project history but misleading/overwhelming for new visitors.

13. Phase 5 PoC - Session 1 Summary 📦 ARCHIVE

  • Why Archive: Project tracking, not end-user documentation
  • Problem: Technical session notes, confusing for general audience
  • Category: none → should be project-tracking
  • Visibility: public → archived

14. Phase 5 PoC - Session 2 Summary 📦 ARCHIVE

  • Why Archive: Project tracking, not end-user documentation
  • Problem: Technical session notes, confusing for general audience
  • Category: none → should be project-tracking
  • Visibility: public → archived

15. Research Scope: Feasibility of LLM-Integrated Tractatus 📦 ARCHIVE

  • Why Archive: Research proposal, not completed work
  • Problem: Marked as "NOT COMPLETED WORK", misleading
  • Category: none → should be research-proposal
  • Visibility: public → archived

16. Research Topic: Concurrent Session Architecture 📦 ARCHIVE

  • Why Archive: Open research question, not documentation
  • Problem: Raises questions without answers
  • Category: none → should be research-topic
  • Visibility: public → archived

17. Research Topic: Rule Proliferation 📦 ARCHIVE

  • Why Archive: Open research question, not documentation
  • Problem: Raises questions without answers
  • Category: none → should be research-topic
  • Visibility: public → archived

Proposed Reorganization

Public Documentation (7 documents, well-organized)

Getting Started (order: 1-3)

  1. Architectural Overview & Research Status (reference)
  2. Core Concepts (conceptual) - UPDATED
  3. Implementation Guide (practical) - UPDATED

Framework Details (order: 4-6) 4. Core Values and Principles (conceptual) 5. Case Studies (practical) 6. Business Case Template (practical)

Reference (order: 7-8) 7. Glossary of Terms (reference) - UPDATED

Archives Section (10 documents, collapsed by default)

Historical Architecture Proposals (collapsed)

  • Introduction to the Tractatus Framework
  • Tractatus-Based LLM Architecture for AI Safety
  • Executive Brief: Tractatus-Based LLM Architecture
  • Organizational Theory Foundations

Development & Tools (collapsed)

  • Tractatus Framework Enforcement for Claude Code

Project Tracking - Phase 5 PoC (collapsed)

  • Session 1 Summary
  • Session 2 Summary

Research Proposals & Topics (collapsed)

  • Research Scope: Feasibility of LLM-Integrated Tractatus
  • Research Topic: Concurrent Session Architecture
  • Research Topic: Rule Proliferation

Implementation Plan

Phase 1: Create Archives Infrastructure

  1. Add visibility field options: public, archived
  2. Add category field options: conceptual, practical, reference, archived, project-tracking, research-proposal, research-topic
  3. Update UI to show archived documents in collapsed section at bottom

Phase 2: Update Current Documents

  1. Core Concepts: Update with Phase 5 MongoDB architecture
  2. Implementation Guide: Rewrite for MongoDB deployment
  3. Glossary: Add Phase 5 terms (MongoDB, MemoryProxy, API Memory)

Phase 3: Archive Outdated Documents

  1. Update 10 documents with visibility: archived
  2. Add archive notes explaining why archived
  3. Set proper categories

Phase 4: Update Metadata

  1. Set proper category for all documents
  2. Set proper audience (general/technical/business/developer)
  3. Set proper order for public documents

Phase 5: UX Testing

  1. Verify docs page shows 7 main documents
  2. Verify archives section collapsed by default
  3. Verify clear categorization
  4. Verify PDF downloads work
  5. Get user feedback

Success Criteria

Before (Current State)

  • ❌ 17 documents overwhelming visitors
  • ❌ No clear categorization
  • ❌ Outdated/contradictory information
  • ❌ Project tracking mixed with public docs
  • ❌ Poor UX for new visitors

After (Target State)

  • ✅ 7 focused, current documents for public
  • ✅ Clear categories (Getting Started, Framework Details, Reference)
  • ✅ All documents current and accurate
  • ✅ 10 archived documents available but not prominent
  • ✅ World-class UX: visitors know exactly where to start

Maintenance Guidelines

When to Archive a Document:

  1. Superseded by newer documentation
  2. References outdated architecture/implementation
  3. Project tracking/research proposals (not end-user docs)
  4. Creates confusion for new visitors

When to Keep a Document:

  1. Current and accurate
  2. Provides unique value (case studies, templates)
  3. Reference material (glossary)
  4. Strategic foundation (values, principles)

When to Update a Document:

  1. Minor inaccuracies (update in place)
  2. New features added (update in place)
  3. Major architecture changes (create new version, archive old)

Next Steps

  1. Get approval for this reorganization plan
  2. Implement archives infrastructure (visibility field, UI changes)
  3. Update Core Concepts, Implementation Guide, Glossary
  4. Archive 10 outdated documents
  5. Test UX improvements
  6. Document maintenance procedures

Prepared by: Claude Code Review Required: John Stroh Estimated Effort: 4-6 hours for full implementation