Skip to main content

ADR-004: Diataxis Framework Integration for Documentation Structure

id: 004-diataxis-framework-integration title: 'ADR-004: Diataxis Framework Integration' sidebar_label: 'ADR-4: Diataxis Framework Integration' sidebar_position: 4​

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​

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​

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​

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;
}
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​

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​

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​