6ceac8f449
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>
283 lines
10 KiB
Markdown
283 lines
10 KiB
Markdown
# 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
|