Skip to main content
Version: 0.2 (Planning MVP)

Business Context & Pain Points

Current State (As-Is)​

Currently, technical documentation is either:

  • Generated as archaic, uncustomizable, and visually outdated HTML files (e.g., standard Doxygen HTML).
  • Manually copied, edited, and maintained in disconnected wiki systems (e.g., Confluence), leading to rapid desynchronization between code and documentation.

Pain Points (Key Motivators)​

The development and maintenance of API and technical documentation using legacy documentation systems (such as Doxygen HTML, Sphinx, or MkDocs) suffer from several critical shortcomings, categorized as follows:

A. UI/UX and Aesthetic Constraints​

  • Visually Outdated Interfaces: Legacy generators produce archaic, non-responsive layouts that fail to align with premium, modern web design standards.
  • Friction in Customization: Modifying standard styles or templates is extremely difficult, requiring manual hacks of complex internal CSS and HTML generation code.
  • Lack of Rich Interactive Features: Default templates lack out-of-the-box interactive components, such as dynamic dark/light mode toggling or interactive multi-language code snippets.
  • Poor Client-Side Search Experience: Standard search bars are slow, non-fuzzy, and mix various reference docs together without advanced relevance scoring or layout division.

B. Build Performance & Bloated Workflows​

  • Unacceptable Compilation Overhead: Rebuilding entire documentation trees for large-scale codebases (thousands of classes) is extremely slow, leading to long developer feedback loops.
  • Bloated CI/CD Dependencies: Legacy generators require heavy runtimes, compilers, or specific environments, increasing the complexity and execution cost of CI/CD pipelines.
  • Excessive Manual Overhead: Current documentation routines require numerous manual trigger and copy-paste steps due to poor automation capabilities and high rigidity of legacy generators.

C. Source Control and Git Hygiene​

  • Repository Pollution and Diff Noise: Committing auto-generated documentation files (HTML or Markdown) directly to Git repositories bloats repository size, creates massive merge conflicts, and obscures meaningful code changes in pull requests.

D. Search Fragmentation & Link Refactoring​

  • Mixed and Incoherent Search Scopes: Inability to separate search databases between administrative docs, user guides, and reference manuals, leading to a cluttered and confusing search experience.
  • Broken Cross-References During Refactoring: Renaming classes, packages, or namespaces silently breaks internal links and cross-references in manual documentation pages, requiring tedious manual repairs.

E. Rigidity & Template Coupling​

  • Tight Parser-Renderer Coupling: The parsing logic is deeply intertwined with the output rendering code, making it highly complex to adapt templates.
  • No Language-Agnostic Intermediate Representation: The lack of a standardized Intermediate Representation (IR) prevents clean decoupling of code parsing from target formatting.
  • Rigid Custom Page Support: Difficulty in generating custom operational pages or custom HTML layouts from the same source structure.
  • Extensibility Overhead: Adapting the documentation pipeline to support new programming languages or target engines requires major structural rewrites.
  • Tooling Stagnation and EOL: Current generation tools (e.g., old versions of parsers or proprietary tools) have ceased active development, resulting in failure to support modern language standards (e.g., C++14/17/20/23 compiler keywords, attributes, and templates).

F. AI/RAG Compatibility & Semantic Gaps​

  • Unstructured Outputs for AI Consumption: Raw generated pages are difficult for LLMs and AI scrapers to ingest, chunk, and interpret with high precision.
  • Missing Rich Semantic Metadata: Key information (such as scope, namespace, variable access levels, and parent relationships) is not represented as structured metadata, preventing accurate embedding generation.
  • No Native JSON RAG Exporter: Lack of a dedicated, high-density JSON export format specifically optimized for Retrieval-Augmented Generation (RAG) pipelines.
  • Coarse-Grained Context Retrieval: Standard layouts cannot easily be chunked at the logical block level (e.g., individual method signatures), resulting in bloated or incomplete context injection in AI assistants.

Desired State (To-Be)​

A modular, pipeline-based system (UDE) that:

  1. Automatically parses structure from code (via Doxygen XML).
  2. Generates clean, SEO-optimized, highly aesthetic documentation.
  3. Integrates seamlessly into modern static hosting providers (GitHub/GitLab Pages).
  4. Employs independent pipelines for project, operational, and reference docs.