layout: default title: ADR-0029 Documentation Strategy parent: Documentation & User Experience grand_parent: Architectural Decision Records nav_order: 2 —

ADR-0029: Documentation Strategy and Website Modernization

Status

In Progress (Infrastructure Complete, Content Migration Pending)

Context

The current Qubinode Navigator documentation infrastructure has critical issues that impact user adoption and project maintainability:

Current Problems

  • Broken Website: https://github.com/Qubinode/qubinode_navigator website is non-functional
  • Fragmented Documentation: Information scattered across multiple markdown files without clear navigation
  • Static Content: Documentation doesn’t reflect dynamic deployment scenarios or real-time guidance
  • Maintenance Overhead: Manual updates required across multiple deployment guides
  • User Experience: New users struggle to find relevant information for their specific scenarios

Documentation Landscape Analysis

  • Deployment Guides: docs/deployments/demo-hetzner-com.markdown, demo-redhat-com.markdown exist but are static
  • ADR Documentation: Well-structured in docs/adrs/ but not publicly accessible
  • Technical Docs: Scattered across repository without unified presentation
  • User Onboarding: No clear getting-started path for different user personas

With the planned AI assistant integration (ADR-0027) and plugin framework (ADR-0028), documentation needs to evolve from static guides to interactive, context-aware assistance.

Decision

Implement a modern, multi-layered documentation strategy that combines traditional documentation with AI-powered interactive guidance:

1. Website Infrastructure Modernization

  • Platform: Migrate to GitHub Pages with Jekyll or modern static site generator (Docusaurus/VitePress)
  • Domain: Establish proper domain with SSL (e.g., qubinode-navigator.dev or GitHub Pages subdomain)
  • CI/CD: Automated deployment from main branch with preview builds for PRs
  • Performance: Fast loading, mobile-responsive, accessible design

2. Documentation Architecture 

Documentation Ecosystem:
├── Public Website (GitHub Pages)
│   ├── Getting Started Guide
│   ├── Architecture Overview  
│   ├── Deployment Scenarios
│   ├── API Documentation
│   └── Community Resources
├── Interactive AI Assistant (ADR-0027)
│   ├── Real-time Deployment Guidance
│   ├── Troubleshooting Support
│   ├── Configuration Validation
│   └── Context-aware Help
└── Developer Documentation
    ├── ADR Repository (docs/adrs/)
    ├── Plugin Development Guide
    ├── Contributing Guidelines
    └── Technical Specifications

3. Content Strategy

  • User-Centric Organization: Documentation organized by user journey, not technical structure
  • Scenario-Based Guides: Replace generic docs with specific deployment scenarios
  • Living Documentation: Auto-generated content from code annotations and plugin metadata
  • Community Contributions: Clear contribution guidelines and review processes

4. AI Integration

  • Documentation RAG: AI assistant trained on all documentation content
  • Interactive Tutorials: AI-guided walkthroughs replacing static markdown guides
  • Dynamic Updates: Documentation that adapts based on user’s environment and choices
  • Feedback Loop: AI learns from user interactions to improve documentation

Consequences

Positive

  • Improved User Experience: Clear, accessible documentation with multiple interaction modes
  • Reduced Support Overhead: AI assistant handles common questions and guidance
  • Better Onboarding: New users can get started quickly with interactive guidance
  • Maintainability: Automated documentation generation reduces manual maintenance
  • Professional Appearance: Working website improves project credibility and adoption
  • Community Growth: Better documentation attracts more contributors and users

Negative

  • Initial Setup Effort: Significant work required to migrate and restructure content
  • Maintenance Complexity: Multiple documentation systems require coordination
  • Learning Curve: Team needs to learn new documentation tools and processes
  • Resource Requirements: Website hosting and domain costs (minimal with GitHub Pages)

Risks

  • Content Drift: Risk of documentation becoming outdated if not properly maintained
  • AI Accuracy: AI assistant may provide incorrect guidance if not properly trained
  • Migration Disruption: Temporary documentation gaps during migration period
  • Tool Dependencies: Reliance on external platforms for documentation hosting

Alternatives Considered

  1. Fix Existing Website Only: Insufficient - doesn’t address fundamental UX and maintenance issues
  2. Documentation-Only Approach: Misses opportunity for AI-enhanced user experience
  3. Third-Party Documentation Platforms: Adds external dependencies and costs
  4. Wiki-Based Documentation: Lacks version control and integration with development workflow
  5. No Documentation Website: Unacceptable for user adoption and project growth

Implementation Plan

Phase 1: Infrastructure Setup (Weeks 1-2)

  • Set up GitHub Pages with modern static site generator
  • Migrate existing content and establish information architecture
  • Implement automated deployment pipeline
  • Create basic navigation and search functionality

Phase 2: Content Migration and Enhancement (Weeks 3-6)

  • Restructure content by user scenarios rather than technical components
  • Create comprehensive getting-started guides for different deployment targets
  • Migrate ADR documentation with proper cross-linking
  • Establish content contribution guidelines and review processes

Phase 3: AI Integration (Weeks 7-10)

  • Integrate documentation content into AI assistant RAG system
  • Create interactive tutorials that replace static deployment guides
  • Implement feedback mechanisms for continuous improvement
  • Test AI guidance accuracy across different deployment scenarios

Phase 4: Community and Optimization (Weeks 11-12)

  • Launch community contribution program
  • Implement analytics and user feedback collection
  • Optimize performance and accessibility
  • Create maintenance and update procedures

Technical Requirements

Website Infrastructure

  • Static Site Generator: Jekyll (GitHub Pages native) or Docusaurus for advanced features
  • Hosting: GitHub Pages with custom domain support
  • CI/CD: GitHub Actions for automated deployment and preview builds
  • Search: Algolia DocSearch or local search implementation
  • Analytics: Privacy-focused analytics (Plausible or GitHub insights)

Content Management

  • Version Control: All documentation in Git with proper branching strategy
  • Review Process: PR-based reviews for documentation changes
  • Automation: Auto-generation of API docs, plugin documentation, and changelogs
  • Validation: Automated link checking and content validation

AI Integration

  • Content Indexing: Structured content format for AI training and retrieval
  • Feedback System: User interaction tracking for AI improvement
  • Update Mechanism: Automated content updates when code or plugins change

Success Metrics

User Experience

  • Website Availability: 99.9% uptime for documentation website
  • User Engagement: Increased time on documentation pages and reduced bounce rate
  • Community Growth: More contributors and community engagement
  • Support Reduction: Decreased support requests for common deployment issues

Content Quality

  • Coverage: Documentation available for all supported deployment scenarios
  • Accuracy: Regular validation of documentation against actual deployment processes
  • Freshness: Automated detection and flagging of outdated content
  • Accessibility: WCAG 2.1 AA compliance for inclusive access

Implementation Progress (2025-11-07)

✅ Completed Infrastructure

  • GitHub Pages Workflow: Automated deployment pipeline created (.github/workflows/deploy-docs.yml)
  • Jekyll Configuration: Site properly configured with Just the Docs theme
  • Documentation Structure: Organized directory structure with navigation
  • Development Guide: Created docs/README.md for contributors
  • ADR Integration: All 31 ADRs properly indexed and categorized

✅ Plugin Framework Documentation Impact

With the successful implementation of ADR-0028 (Plugin Framework), documentation strategy has evolved:

Static Documentation → Dynamic Plugin-Aware Content

  • Legacy Approach: Static markdown files for each deployment scenario
    • docs/deployments/demo-hetzner-com.markdown → HetznerDeploymentPlugin
    • docs/deployments/demo-redhat-com.markdown → RedHatDemoPlugin + EquinixPlugin

Modern Approach: Plugin-Generated Documentation

  • Setup Process: setup.sh → setup_modernized.sh with intelligent guidance
  • Deployment Guides: Static guides → Plugin-driven interactive workflows
  • Configuration: Manual config files → Plugin-managed configuration validation

✅ Setup Script Integration (ADR-0031)

The modernized setup script now provides:

  • Intelligent Environment Detection: Automatic OS and cloud provider detection
  • Dynamic Next Steps: Context-aware guidance based on detected environment
  • Plugin Status Integration: Real-time plugin execution results and recommendations

🔄 Pending Content Migration

  • Update deployment guides to reference plugin-based workflows
  • Create plugin-specific documentation pages
  • Migrate static deployment scenarios to interactive plugin guides
  • Add plugin development documentation
  • Create troubleshooting guides for plugin framework

📋 Updated Documentation Architecture 

Documentation Ecosystem (Implemented):
├── Public Website (GitHub Pages) ✅
│   ├── Jekyll + Just the Docs Theme ✅
│   ├── Automated CI/CD Pipeline ✅
│   ├── ADR Documentation (31 ADRs) ✅
│   └── Plugin Framework Overview ✅
├── Plugin-Driven Guidance ✅
│   ├── setup_modernized.sh (intelligent setup) ✅
│   ├── qubinode_cli.py (plugin management) ✅
│   ├── Dynamic environment detection ✅
│   └── Context-aware next steps ✅
└── Developer Documentation ✅
    ├── Plugin Development Framework ✅
    ├── Core API Documentation ✅
    └── Configuration Management ✅
  • ADR-0027: CPU-Based AI Deployment Assistant Architecture (AI integration)
  • ADR-0028: Modular Plugin Framework for Extensibility (plugin documentation) ✅ Implemented
  • ADR-0026: RHEL 10/CentOS 10 Platform Support Strategy (new deployment scenarios) ✅ Implemented
  • ADR-0031: Setup Script Modernization Strategy (setup documentation integration) ✅ Implemented

Date

2025-11-07

Stakeholders

  • Documentation Team
  • UX/Product Team
  • DevOps Team
  • Community Contributors
  • End Users