2298d36bed
- Create Economist SubmissionTracking package correctly: * mainArticle = full blog post content * coverLetter = 216-word SIR— letter * Links to blog post via blogPostId - Archive 'Letter to The Economist' from blog posts (it's the cover letter) - Fix date display on article cards (use published_at) - Target publication already displaying via blue badge Database changes: - Make blogPostId optional in SubmissionTracking model - Economist package ID: 68fa85ae49d4900e7f2ecd83 - Le Monde package ID: 68fa2abd2e6acd5691932150 Next: Enhanced modal with tabs, validation, export 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
228 lines
6.7 KiB
Markdown
228 lines
6.7 KiB
Markdown
# Tractatus Documentation Reorganization Summary
|
|
**Date**: 2025-10-11
|
|
|
|
---
|
|
|
|
## Why This Reorganization?
|
|
|
|
**Answer to your question**: I needed to install `mongoose` and `@anthropic-ai/sdk` because I deployed TOO MUCH at once. The commit included:
|
|
- The .md file (✅ needed)
|
|
- Framework service enhancements (❌ shouldn't have deployed)
|
|
- MongoDB models requiring mongoose (❌ side effect)
|
|
- Services requiring @anthropic-ai/sdk (❌ side effect)
|
|
|
|
**Lesson**: Documentation deployment should NOT require framework dependencies. This indicates poor separation of concerns in the deployment process.
|
|
|
|
---
|
|
|
|
## Current State: 17 Documents → Too Many, Poorly Organized
|
|
|
|
```
|
|
PUBLIC DOCUMENTATION (17 documents, no categorization)
|
|
├── ❌ No clear "start here" path
|
|
├── ❌ Outdated docs contradict current implementation
|
|
├── ❌ Project tracking mixed with end-user docs
|
|
├── ❌ Research proposals confuse visitors
|
|
└── ❌ New visitors overwhelmed
|
|
```
|
|
|
|
---
|
|
|
|
## Proposed State: 7 + 10 Archives → Clear, Current, World-Class UX
|
|
|
|
```
|
|
PUBLIC DOCUMENTATION (7 documents, clear structure)
|
|
│
|
|
├── 📘 GETTING STARTED (order: 1-3)
|
|
│ ├── 1. Architectural Overview ✅ CURRENT
|
|
│ ├── 2. Core Concepts ⚠️ UPDATE
|
|
│ └── 3. Implementation Guide ⚠️ UPDATE
|
|
│
|
|
├── 📗 FRAMEWORK DETAILS (order: 4-6)
|
|
│ ├── 4. Core Values & Principles ✅ CURRENT
|
|
│ ├── 5. Case Studies ✅ CURRENT
|
|
│ └── 6. Business Case Template ✅ CURRENT
|
|
│
|
|
└── 📕 REFERENCE (order: 7)
|
|
└── 7. Glossary of Terms ⚠️ UPDATE
|
|
|
|
📦 ARCHIVES (10 documents, collapsed section at bottom)
|
|
│
|
|
├── Historical Architecture Proposals (4)
|
|
│ ├── Introduction to Tractatus (superseded)
|
|
│ ├── LLM Architecture Spec (pre-Phase 5)
|
|
│ ├── Executive Brief (pre-Phase 5)
|
|
│ └── Organizational Theory (academic)
|
|
│
|
|
├── Development Tools (1)
|
|
│ └── Framework Enforcement for Claude Code
|
|
│
|
|
├── Project Tracking - Phase 5 (2)
|
|
│ ├── Session 1 Summary
|
|
│ └── Session 2 Summary
|
|
│
|
|
└── Research Proposals (3)
|
|
├── Feasibility Research Scope
|
|
├── Concurrent Session Architecture
|
|
└── Rule Proliferation
|
|
```
|
|
|
|
---
|
|
|
|
## Document Actions Summary
|
|
|
|
| Action | Count | Documents |
|
|
|--------|-------|-----------|
|
|
| ✅ **KEEP AS-IS** | 4 | Architectural Overview, Core Values, Case Studies, Business Template |
|
|
| ⚠️ **UPDATE** | 3 | Core Concepts, Implementation Guide, Glossary |
|
|
| 📦 **ARCHIVE** | 10 | See Archives section above |
|
|
| **Total** | 17 | → 7 public + 10 archived |
|
|
|
|
---
|
|
|
|
## What Needs Updating?
|
|
|
|
### 1. Core Concepts (CRITICAL)
|
|
**Problem**: References 5 services, now 6. No MongoDB mention.
|
|
**Fix**:
|
|
- Add MongoDB persistence layer
|
|
- Add 6th service (BlogCuration)
|
|
- Add API Memory integration
|
|
- Reference architectural overview for details
|
|
|
|
### 2. Implementation Guide (CRITICAL)
|
|
**Problem**: Shows filesystem-only setup, pre-MongoDB.
|
|
**Fix**:
|
|
- MongoDB setup instructions
|
|
- Environment variables (MONGODB_URI, MONGODB_DB)
|
|
- Remove `.claude/instruction-history.json` references
|
|
- Add production deployment section
|
|
- Update code examples
|
|
|
|
### 3. Glossary (MEDIUM)
|
|
**Problem**: Missing Phase 5 terms.
|
|
**Fix**:
|
|
- Add: MongoDB, MemoryProxy, API Memory, Hybrid Architecture
|
|
- Update: Persistence mechanism definitions
|
|
|
|
---
|
|
|
|
## UX Improvements
|
|
|
|
### Before (Current)
|
|
```
|
|
Visitor lands on docs page:
|
|
"17 documents... which do I read first?"
|
|
"Some talk about filesystem, some about MongoDB... which is current?"
|
|
"Why are there session summaries here?"
|
|
"Is this a research proposal or actual documentation?"
|
|
→ Confusion, high bounce rate
|
|
```
|
|
|
|
### After (Proposed)
|
|
```
|
|
Visitor lands on docs page:
|
|
📘 GETTING STARTED
|
|
→ Clear entry point: Architectural Overview
|
|
→ Only 3 documents to get started
|
|
|
|
📗 FRAMEWORK DETAILS
|
|
→ 3 focused documents for deeper understanding
|
|
|
|
📕 REFERENCE
|
|
→ Glossary for quick lookups
|
|
|
|
📦 ARCHIVES (collapsed)
|
|
→ Historical content available but not prominent
|
|
|
|
→ Clear path, low friction, professional UX
|
|
```
|
|
|
|
---
|
|
|
|
## Implementation Checklist
|
|
|
|
### Phase 1: Archives Infrastructure ⏱️ ~1 hour
|
|
- [ ] Add `visibility` enum: `public`, `archived`
|
|
- [ ] Add `category` enum: `conceptual`, `practical`, `reference`, `archived`, `project-tracking`, `research-proposal`
|
|
- [ ] Update docs UI to show archives section (collapsed by default)
|
|
- [ ] Test archives section rendering
|
|
|
|
### Phase 2: Update Current Docs ⏱️ ~2-3 hours
|
|
- [ ] Update Core Concepts (MongoDB, 6 services, API Memory)
|
|
- [ ] Rewrite Implementation Guide (MongoDB setup, env vars, deployment)
|
|
- [ ] Update Glossary (add Phase 5 terms)
|
|
- [ ] Test all updated docs for accuracy
|
|
|
|
### Phase 3: Archive Outdated Docs ⏱️ ~30 minutes
|
|
- [ ] Set `visibility: archived` for 10 documents
|
|
- [ ] Add `archiveNote` field explaining why archived
|
|
- [ ] Set proper categories for all archived docs
|
|
- [ ] Test archived documents still accessible via direct link
|
|
|
|
### Phase 4: Metadata & Ordering ⏱️ ~30 minutes
|
|
- [ ] Set `category` for all 7 public documents
|
|
- [ ] Set `audience` appropriately
|
|
- [ ] Set `order` 1-7 for public documents
|
|
- [ ] Set `order: 999` for archived documents
|
|
|
|
### Phase 5: Testing & Validation ⏱️ ~30 minutes
|
|
- [ ] Verify docs page shows 7 main documents only
|
|
- [ ] Verify archives section collapsed by default
|
|
- [ ] Verify all PDFs download correctly
|
|
- [ ] Verify mobile responsiveness
|
|
- [ ] Get user feedback
|
|
|
|
**Total Estimated Effort**: 4-6 hours
|
|
|
|
---
|
|
|
|
## Success Metrics
|
|
|
|
| Metric | Before | After | Goal |
|
|
|--------|--------|-------|------|
|
|
| Public docs count | 17 | 7 | ✅ 60% reduction |
|
|
| Outdated docs visible | 10 | 0 | ✅ 100% reduction |
|
|
| Clear categorization | 0/17 | 7/7 | ✅ 100% improvement |
|
|
| "Start here" clarity | None | Clear | ✅ Obvious entry point |
|
|
| Updated for Phase 5 | 1/17 | 7/7 | ✅ 100% current |
|
|
|
|
---
|
|
|
|
## Decision Required
|
|
|
|
**Option A: Full Reorganization** (Recommended)
|
|
- Implement all 5 phases
|
|
- 4-6 hours effort
|
|
- Result: World-class UX
|
|
|
|
**Option B: Minimal Update**
|
|
- Just update Core Concepts, Implementation Guide, Glossary
|
|
- 2-3 hours effort
|
|
- Result: Better accuracy, but still cluttered
|
|
|
|
**Option C: Archive Only**
|
|
- Just hide outdated docs
|
|
- 1 hour effort
|
|
- Result: Less clutter, but remaining docs still inaccurate
|
|
|
|
**Recommendation**: **Option A** - Full reorganization for world-class UX
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
1. **Review this summary** and audit document
|
|
2. **Approve reorganization plan** (or request modifications)
|
|
3. **Schedule implementation** (4-6 hour window)
|
|
4. **Execute phases 1-5**
|
|
5. **Test and validate**
|
|
6. **Monitor user feedback**
|
|
|
|
---
|
|
|
|
**Questions?**
|
|
- Which documents should stay/go?
|
|
- Different categorization scheme?
|
|
- Timing preferences?
|
|
- Other concerns?
|