Architecture: How should we organize MCP documentation to improve navigati...

Documentation for Sessions

🏗️ Architecture: How should we organize MCP documentation to improve navigati...

📋 Decision Context

Question:

How should we organize MCP documentation to improve navigation and maintainability?

Task: Reorganize MCP documentation from flat structure to organized hierarchy - Session 30.1

🎯 Decision Made

Chosen:

Create 8 focused sub-directories (01-getting-started through 08-roadmap) with README.md for each, move existing docs to appropriate sections, consolidate overlapping content

Options Considered:

  1. Keep flat structure with 10 files
  2. Create sub-directories with organized hierarchy
  3. Move to single massive document
  4. Keep current structure but add index
  5. Use wiki-style interlinking only

💭 Reasoning

The flat structure violated AGENTS.md principle of 5-8 organized files per section and was causing navigation issues. Created 8 themed directories (getting-started, setup, usage, architecture, training, command-center, development, roadmap) following progressive learning path. Each directory has README.md for navigation. This mirrors Session 7's documentation consolidation success (39 files → 7 organized). Benefits: (1) Clear learning path for new users, (2) Easy to find specific information, (3) Scalable structure for future docs, (4) Follows project documentation standards, (5) Separates setup from usage from architecture. Moved CLAUDE-CODE-SETUP.md to 02-setup/claude-code-setup.md (keeps recent verified content), consolidated training docs into 05-training/, separated current vs future Command Center docs. Left placeholders for Phase 2 content (getting-started, usage, development). Total: 18 organized files vs 10 cluttered files.

📁 Files Involved

🔗 Related

Auto-generated by MCP Smart Consolidation