Skip to main content

DITA Integration Strategy for LLM Platform

Overview​

This document outlines the comprehensive integration of Darwin Information Typing Architecture (DITA) across all LLM Platform projects. The goal is to create a unified, professional documentation ecosystem that scales from individual components to platform-wide documentation.

Implementation Phases​

Phase 1: Core Infrastructure (Immediate)​

  1. Central DITA Repository

    • Create shared DITA resources in /LLM/dita-shared/
    • Common keydefs, conrefs, and templates
    • Shared CSS and branding elements
    • Master build scripts

  2. Project Templates

    • Standard DITA structure for each project type
    • TypeScript/Node.js project template
    • Drupal module template
    • Infrastructure component template

Phase 2: High-Priority Projects (Week 1)​

  • llm (Core Drupal module)
  • llmcli (Primary CLI tool)
  • gov_compliance (Critical for government deployments)
  • api_normalizer (Key integration component)

Phase 3: Supporting Projects (Week 2)​

  • tddai (Development standards enforcer)
  • llm-gateway (API infrastructure)
  • llm-mcp (Protocol implementation)
  • alternative_services (Service discovery)

Phase 4: Extended Ecosystem (Week 3+)​

  • All AI agent modules
  • AI provider modules
  • Infrastructure components
  • Deployment configurations

DITA Structure Per Project​

Standard Project DITA Layout​

project-root/
├── dita/
│   ├── project.ditamap          # Project-specific map
│   ├── topics/
│   │   ├── overview.dita        # Project overview
│   │   ├── installation.dita   # Installation guide
│   │   ├── configuration.dita  # Configuration reference
│   │   ├── api-reference.dita  # API documentation
│   │   ├── troubleshooting.dita # Common issues
│   │   └── changelog.dita      # Version history
│   ├── shared/                  # Symlink to central resources
│   └── build.xml               # Project-specific build config
├── docs/                       # Generated documentation
└── scripts/
    └── build-docs.sh          # Local build script

Content Types by Project Type​

TypeScript/Node.js Projects​

  • Concepts: Architecture, design patterns, integration points
  • Tasks: Installation, configuration, development workflows
  • References: API documentation, CLI commands, configuration options

Drupal Modules​

  • Concepts: Module purpose, entity types, plugin system
  • Tasks: Installation, configuration, usage workflows
  • References: Hooks, services, permissions, settings

Infrastructure Components​

  • Concepts: Architecture, security model, scaling strategies
  • Tasks: Deployment, configuration, monitoring setup
  • References: Helm values, environment variables, metrics

Automated Content Generation​

Code-to-DITA Generators​

  1. TypeScript/JavaScript

    • Extract JSDoc comments to DITA reference topics
    • Generate API documentation from TypeScript interfaces
    • Create CLI command reference from command definitions

  2. PHP/Drupal

    • Extract docblock comments to DITA topics
    • Generate hook documentation from implementations
    • Create service documentation from annotations

  3. Infrastructure

    • Generate Helm chart documentation from values.yaml
    • Create environment variable reference from configs
    • Document Docker image configurations

Integration with Existing Tools​

llmcli Integration​

# New DITA commands for llmcli
llmcli dita init [project]      # Initialize DITA for a project
llmcli dita build [project]     # Build DITA documentation
llmcli dita validate [project]  # Validate DITA content
llmcli dita generate [type]     # Generate DITA from code

tddai Integration​

  • Add DITA documentation coverage to TDD score
  • Enforce documentation standards
  • Auto-generate missing documentation stubs

CI/CD Integration​

  • Automated DITA validation in pipelines
  • Documentation building on releases
  • Publishing to central documentation site

Shared Resources​

Key Definitions (keydefs.ditamap)​

<keydef keys="company-name"><topicmeta><keywords><keyword>Bluefly</keyword></keywords></topicmeta></keydef>
<keydef keys="platform-name"><topicmeta><keywords><keyword>LLM Platform</keyword></keywords></topicmeta></keydef>
<keydef keys="default-ai-provider"><topicmeta><keywords><keyword>Ollama</keyword></keywords></topicmeta></keydef>

Common Warnings/Notes (common-content.dita)​

<topic id="common-content">
  <note id="security-warning" type="warning">This operation requires appropriate security clearance and audit logging.</note>
  <note id="api-key-note" type="important">Never commit API keys or secrets to version control.</note>
</topic>

Conditional Processing Profiles​

  • audience: developer, admin, user, integrator
  • platform: kubernetes, docker, local, cloud
  • security-level: public, confidential, secret, top-secret

Master Documentation Portal​

Aggregated Documentation Structure​

/LLM/documentation-portal/
├── master.ditamap              # Combines all project maps
├── platform-overview.ditamap   # High-level platform docs
├── projects/
│   ├── drupal-modules.ditamap # All Drupal module docs
│   ├── npm-packages.ditamap   # All NPM package docs
│   └── infrastructure.ditamap # All infrastructure docs
└── build-all.sh              # Master build script

Quality Standards​

DITA Best Practices​

  1. Topic Granularity: One concept/task/reference per file
  2. ID Conventions: Consistent, meaningful topic IDs
  3. Metadata: Complete metadata for all topics
  4. Linking: Use keyrefs and conrefs for maintainability
  5. Validation: All content must validate against DTD

Review Process​

  1. Automated validation in PR checks
  2. Documentation review alongside code review
  3. Cross-project consistency checks
  4. Terminology consistency enforcement

Metrics and Success Criteria​

Coverage Metrics​

  • 100% of public APIs documented
  • 100% of configuration options documented
  • 90%+ of common tasks documented
  • 80%+ of troubleshooting scenarios covered

Quality Metrics​

  • Zero validation errors
  • <5% duplicate content (use conrefs)
  • 100% of external links validated
  • Consistent terminology usage

Implementation Timeline​

Week 1​

  • Set up shared DITA infrastructure
  • Implement templates and generators
  • Complete Phase 2 projects

Week 2​

  • Extend llmcli with DITA commands
  • Complete Phase 3 projects
  • Set up CI/CD integration

Week 3​

  • Complete remaining projects
  • Build master documentation portal
  • Launch unified documentation site

Benefits​

  1. Professional Documentation: Enterprise-grade technical documentation
  2. Consistency: Uniform structure and style across all projects
  3. Efficiency: Reuse common content, reduce duplication
  4. Maintainability: Single source of truth for shared concepts
  5. Flexibility: Generate multiple output formats from single source
  6. Scalability: Easy to add new projects and content
  7. Searchability: Unified search across all project documentation
  8. Versioning: Document multiple versions simultaneously
  9. Localization: Built-in support for translations
  10. Compliance: Meets government documentation requirements

This comprehensive DITA integration will transform the LLM Platform's documentation from scattered README files into a professional, maintainable, and scalable documentation system worthy of an enterprise platform.