Deduplicate and simplify documentation #61
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Added three detailed analysis documents identifying duplicate content across documentation: - DEDUPLICATION_AUDIT.md: Complete analysis with severity ratings and recommendations - DEDUP_QUICK_REFERENCE.md: At-a-glance summary and action items - DEDUP_FILE_REFERENCE.md: Exact file paths and line numbers for duplications Key findings: - ~4,000+ lines of duplicate content identified across 77 MDX files - 1,700-2,300 lines actionable cleanup (9-13% reduction) - 3 critical conflicts including JSON vs Markdown guidance - Prioritized action plan with time estimates Major issues: 1. Tool design guidance scattered across 3 files (2,485 lines) 2. Setup instructions duplicated in 3 files (250+ lines) 3. Security guidance fragmented across multiple files (500+ lines)
Added comprehensive analysis for separating conceptual vs procedural content: - DOCUMENTATION_ANALYSIS_REPORT.md: Detailed file-by-file breakdown with line numbers - DOCUMENTATION_ACTION_CHECKLIST.md: Step-by-step implementation checklist Key findings: - why-webmcp.mdx (100% conceptual) incorrectly placed in Documentation tab - 3 missing Concepts pages: agent-threat-model, tool-routing, tool-composition - Documentation tab has 30-40% conceptual content that should link to Concepts - Detailed migration plan with 10-12 hour implementation estimate Proposed structure: - Documentation tab: Pure action-oriented "how to" guides - Concepts tab: Theory, architecture, and design philosophy - Cross-links between tabs for seamless navigation
… content Major restructuring to align Documentation tab with action-oriented content and Concepts tab with theoretical/architectural content. Changes: - Moved why-webmcp.mdx → concepts/alternatives.mdx (100% conceptual content) - Created concepts/agent-threat-model.mdx (security architecture and threat modeling) - Created concepts/tool-routing.mdx (multi-tab collection architecture) - Created concepts/tool-composition.mdx (cross-site composition patterns) - Updated docs.json navigation to reflect new structure - Added new "Architecture & Patterns" group in Concepts tab - Added cross-references from Documentation pages to Concepts pages Updated files: - introduction.mdx: Updated link to concepts/alternatives - security.mdx: Added link to concepts/agent-threat-model - advanced.mdx: Added links to concepts/tool-routing and concepts/tool-composition - best-practices.mdx: Added links to tool-design, performance, and agent-threat-model concepts - connecting-agents.mdx: Added link to concepts/architecture Impact: - Documentation tab now focuses on "how to do X" (action-oriented) - Concepts tab provides "why and how it works" (theory and architecture) - Clear separation improves navigation and reduces cognitive load - Users can deep dive into architecture without cluttering procedural guides
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.