documcp

--- id: 004-diataxis-framework-integration title: "ADR-004: Diataxis Framework Integration" sidebar_label: "ADR-4: Diataxis Framework Integration" sidebar_position: 4 --- # ADR-004: Diataxis Framework Integration for Documentation Structure ## Status Accepted ## Context DocuMCP aims to improve the quality and effectiveness of technical documentation by implementing proven information architecture principles. The Diataxis framework provides a systematic approach to organizing technical documentation into four distinct categories that serve different user needs and learning contexts. Diataxis Framework Components: - **Tutorials**: Learning-oriented content for skill acquisition - **How-to Guides**: Problem-solving oriented content for specific tasks - **Technical Reference**: Information-oriented content for lookup and verification - **Explanation**: Understanding-oriented content for context and background Current documentation challenges: - Most projects mix different content types without clear organization - Users struggle to find appropriate content for their current needs - Documentation often fails to serve different user contexts effectively - Information architecture is typically ad-hoc and inconsistent The framework addresses fundamental differences in user intent: - **Study vs. Work**: Different contexts require different content approaches - **Acquisition vs. Application**: Learning new skills vs. applying existing knowledge - **Practical vs. Theoretical**: Task completion vs. understanding concepts ## Decision We will integrate the Diataxis framework as the foundational information architecture for all DocuMCP-generated documentation structures, with intelligent content planning and navigation generation adapted to each static site generator's capabilities. ### Integration Approach: #### 1. Automated Structure Generation - **Directory organization** that clearly separates Diataxis content types - **Navigation systems** that help users understand content categorization - **Template generation** for each content type with appropriate guidance - **Cross-reference systems** that maintain logical relationships between content types #### 2. Content Type Templates - **Tutorial templates** with learning objectives, prerequisites, step-by-step instructions - **How-to guide templates** focused on problem-solution patterns - **Reference templates** for systematic information organization - **Explanation templates** for conceptual and architectural content #### 3. Content Planning Intelligence - **Automated content suggestions** based on project analysis - **Gap identification** for missing content types - **User journey mapping** to appropriate content categories - **Content relationship mapping** to ensure comprehensive coverage #### 4. SSG-Specific Implementation - **Adaptation to SSG capabilities** while maintaining Diataxis principles - **Theme and plugin recommendations** that support Diataxis organization - **Navigation configuration** optimized for each SSG's features ## Alternatives Considered ### Generic Documentation Templates - **Pros**: Simpler implementation, fewer constraints on content organization - **Cons**: Perpetuates existing documentation quality problems, no systematic improvement - **Decision**: Rejected due to missed opportunity for significant quality improvement ### Custom Documentation Framework - **Pros**: Full control over documentation approach and features - **Cons**: Reinventing proven methodology, reduced credibility, maintenance burden - **Decision**: Rejected in favor of proven, established framework ### Multiple Framework Options - **Pros**: Could accommodate different project preferences and approaches - **Cons**: Choice paralysis, inconsistent quality, complex implementation - **Decision**: Rejected to maintain focus and ensure consistent quality outcomes ### Optional Diataxis Integration - **Pros**: Gives users choice, accommodates existing documentation structures - **Cons**: Reduces value proposition, complicates implementation, inconsistent results - **Decision**: Rejected to ensure consistent quality and educational value ## Consequences ### Positive - **Improved Documentation Quality**: Systematic application of proven principles - **Better User Experience**: Users can find appropriate content for their context - **Educational Value**: Projects learn proper documentation organization - **Consistency**: All DocuMCP projects benefit from same high-quality structure - **Maintenance Benefits**: Clear content types simplify ongoing documentation work ### Negative - **Learning Curve**: Teams need to understand Diataxis principles for optimal results - **Initial Overhead**: More structure requires more initial planning and content creation - **Rigidity**: Some projects might prefer different organizational approaches ### Risks and Mitigations - **User Resistance**: Provide clear education about benefits and implementation guidance - **Implementation Complexity**: Start with basic structure, enhance over time - **Content Quality**: Provide high-quality templates and examples ## Implementation Details ### Directory Structure Generation ```typescript interface DiataxisStructure { tutorials: DirectoryConfig; howToGuides: DirectoryConfig; reference: DirectoryConfig; explanation: DirectoryConfig; navigation: NavigationConfig; } const DIATAXIS_TEMPLATES: Record<SSGType, DiataxisStructure> = { hugo: { tutorials: { path: "content/tutorials", layout: "tutorial" }, howToGuides: { path: "content/how-to", layout: "guide" }, reference: { path: "content/reference", layout: "reference" }, explanation: { path: "content/explanation", layout: "explanation" }, navigation: { menu: "diataxis", weight: "category-based" }, }, // ... other SSG configurations }; ``` ### Content Template System ```typescript interface ContentTemplate { frontmatter: Record<string, any>; structure: ContentSection[]; guidance: string[]; examples: string[]; } const TUTORIAL_TEMPLATE: ContentTemplate = { frontmatter: { title: "{{ tutorial_title }}", description: "{{ tutorial_description }}", difficulty: "{{ difficulty_level }}", prerequisites: "{{ prerequisites }}", estimated_time: "{{ time_estimate }}", }, structure: [ { section: "learning_objectives", required: true }, { section: "prerequisites", required: true }, { section: "step_by_step_instructions", required: true }, { section: "verification", required: true }, { section: "next_steps", required: false }, ], guidance: [ "Focus on learning and skill acquisition", "Provide complete, working examples", "Include verification steps for each major milestone", "Assume minimal prior knowledge", ], }; ``` ### Content Planning Algorithm ```typescript interface ContentPlan { tutorials: TutorialSuggestion[]; howToGuides: HowToSuggestion[]; reference: ReferenceSuggestion[]; explanation: ExplanationSuggestion[]; } function generateContentPlan(projectAnalysis: ProjectAnalysis): ContentPlan { return { tutorials: suggestTutorials(projectAnalysis), howToGuides: suggestHowToGuides(projectAnalysis), reference: suggestReference(projectAnalysis), explanation: suggestExplanation(projectAnalysis), }; } function suggestTutorials(analysis: ProjectAnalysis): TutorialSuggestion[] { const suggestions: TutorialSuggestion[] = []; // Getting started tutorial (always recommended) suggestions.push({ title: "Getting Started", description: "First steps with {{ project_name }}", priority: "high", estimated_effort: "medium", }); // Feature-specific tutorials based on project complexity if (analysis.complexity.apiSurface > 5) { suggestions.push({ title: "API Integration Tutorial", description: "Complete guide to integrating with the API", priority: "high", estimated_effort: "large", }); } return suggestions; } ``` ### Navigation Generation ```typescript interface DiataxisNavigation { structure: NavigationItem[]; labels: NavigationLabels; descriptions: CategoryDescriptions; } const NAVIGATION_STRUCTURE: DiataxisNavigation = { structure: [ { category: "tutorials", label: "Tutorials", description: "Learning-oriented guides", icon: "graduation-cap", order: 1, }, { category: "how-to", label: "How-to Guides", description: "Problem-solving recipes", icon: "tools", order: 2, }, { category: "reference", label: "Reference", description: "Technical information", icon: "book", order: 3, }, { category: "explanation", label: "Explanation", description: "Understanding and context", icon: "lightbulb", order: 4, }, ], labels: { tutorials: "Learn", howToGuides: "Solve", reference: "Lookup", explanation: "Understand", }, descriptions: { tutorials: "Step-by-step learning paths", howToGuides: "Solutions to specific problems", reference: "Complete technical details", explanation: "Background and concepts", }, }; ``` ### SSG-Specific Adaptations ```typescript interface SSGDiataxisAdapter { generateStructure( ssg: SSGType, project: ProjectAnalysis, ): DiataxisImplementation; createNavigation( ssg: SSGType, structure: DiataxisStructure, ): NavigationConfig; generateTemplates(ssg: SSGType, contentTypes: ContentType[]): TemplateSet; } class HugoDiataxisAdapter implements SSGDiataxisAdapter { generateStructure( ssg: SSGType, project: ProjectAnalysis, ): DiataxisImplementation { return { contentDirectories: this.createHugoContentStructure(), frontmatterSchemas: this.createHugoFrontmatter(), taxonomies: this.createDiataxisTaxonomies(), menuConfiguration: this.createHugoMenus(), }; } createHugoContentStructure(): ContentStructure { return { "content/tutorials/": { weight: 10, section: "tutorials" }, "content/how-to/": { weight: 20, section: "guides" }, "content/reference/": { weight: 30, section: "reference" }, "content/explanation/": { weight: 40, section: "explanation" }, }; } } ``` ## Quality Assurance ### Diataxis Compliance Validation ```typescript interface DiataxisValidator { validateStructure(documentation: DocumentationStructure): ValidationResult; checkContentTypeAlignment( content: Content, declaredType: ContentType, ): AlignmentResult; identifyMissingCategories(structure: DocumentationStructure): Gap[]; } function validateDiataxisCompliance( docs: DocumentationStructure, ): ComplianceReport { return { structureCompliance: checkDirectoryOrganization(docs), contentTypeAccuracy: validateContentCategorization(docs), navigationClarity: assessNavigationEffectiveness(docs), crossReferenceCompleteness: checkContentRelationships(docs), }; } ``` ### Content Quality Guidelines - **Tutorial Content**: Must include learning objectives, prerequisites, and verification steps - **How-to Content**: Must focus on specific problems with clear solution steps - **Reference Content**: Must be comprehensive, accurate, and systematically organized - **Explanation Content**: Must provide context, background, and conceptual understanding ### Testing Strategy - **Structure Tests**: Validate directory organization and navigation generation - **Template Tests**: Ensure all content type templates are properly formatted - **Integration Tests**: Test complete Diataxis implementation across different SSGs - **User Experience Tests**: Validate that users can effectively navigate and find content ## Educational Integration ### User Guidance - **Diataxis Explanation**: Clear documentation of framework benefits and principles - **Content Type Guidelines**: Detailed guidance for creating each type of content - **Migration Assistance**: Help converting existing documentation to Diataxis structure - **Best Practice Examples**: Templates and examples demonstrating effective implementation ### Community Building - **Diataxis Advocacy**: Promote framework adoption across open-source community - **Success Story Sharing**: Highlight projects benefiting from Diataxis implementation - **Training Resources**: Develop educational materials for technical writers and maintainers - **Feedback Collection**: Gather community input for framework implementation improvements ## Future Enhancements ### Advanced Features - **Content Gap Analysis**: AI-powered identification of missing content areas - **User Journey Optimization**: Intelligent linking between content types based on user flows - **Content Quality Scoring**: Automated assessment of content quality within each category - **Personalized Navigation**: Adaptive navigation based on user role and experience level ### Tool Integration - **Analytics Integration**: Track how users navigate between different content types - **Content Management**: Tools for maintaining Diataxis compliance over time - **Translation Support**: Multi-language implementations of Diataxis structure - **Accessibility Features**: Ensure Diataxis implementation supports accessibility standards ## References - [Diataxis Framework Official Documentation](https://diataxis.fr/) - [Information Architecture Principles](https://www.usability.gov/what-and-why/information-architecture.html) - [Technical Writing Best Practices](https://developers.google.com/tech-writing)