Mermaid diagrams to enhance the post structure

Author: alandefreitas

_posts/2025-10-28-Alan.md

@@ -25,6 +25,30 @@ Unlike single-purpose generators, MrDocs separates the **corpus** (semantic data
 
 From the user’s perspective, MrDocs behaves like a **well-engineered CLI utility**. It accepts **configuration files**, supports **relative paths**, accepts custom **build options**, and reports **warnings** in a controlled, **compiler-like** fashion. For C++ teams transitioning from **Doxygen**, the **command structure** is somewhat familiar, but the **internal model** is designed for **reproducibility** and **correctness**. Our goal is not just to render **reference pages** but to provide a **reliable pipeline** that any C++ project seeking **modern documentation infrastructure** can adopt.
 
+{% mermaid %}
+graph LR
+  A[Source] --> B[Clang]
+  B --> C[Corpus]
+  C --> D{Plugin Layer}
+  subgraph Generator
+    E[HTML]
+    F[AsciiDoc]
+    G[XML]
+    G2[...]
+  end
+  D --> E
+  D --> F
+  D --> G
+  D --> G2
+  E --> H{Plugin Layer}
+  H --> H2[Published Docs]
+  F --> H
+  G --> H
+  G2 --> H
+  C --> I[Schema Export]
+  I --> J[Integrations<br/>IDEs & Build Systems]
+{% endmermaid %}
+
 ## 2024: Lessons from a Fragile Prototype
 
 MrDocs entered 2024 as a proof-of-concept built for Boost.URL. It could document one or two curated codebases and produce asciidoc pages for Antora, but the workflow stopped there. The CLI exposed only the scenarios we needed. Configuration options lived in internal notes. The only dependable build path was the script sequence we used inside the Alliance. External users hit errors and missing options almost immediately.
@@ -46,6 +70,18 @@ In short:
 - Every improvement exposed another weak link, and every success demanded more structure than the system was built to handle.  
 - It was a year of learning by exhaustion—and setting the stage for everything that came next.
 
+Key 2024 checkpoints align with the timeline below:
+
+{% mermaid %}
+%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#f7f9ff", "primaryBorderColor": "#9aa7e8", "primaryTextColor": "#1f2a44", "lineColor": "#b4bef2", "secondaryColor": "#fbf8ff", "tertiaryColor": "#ffffff", "fontSize": "14px"}}}%%
+timeline
+  title Prototypes
+  2024 Q1 : Boost.URL showcase
+  2024 Q2 : CLI gaps
+  2024 Q3 : Config + SFINAE fixes
+  2024 Q4 : Leadership transition
+{% endmermaid %}
+
 # 2025: From Prototype to MVP
 
 I started the year with a gap analysis that compared MrDocs to other C++ documentation pipelines. From that review I defined the minimum viable product and three priority tracks. **Usability** covered workflows and surface area that make adoption simple. **Stability** covered deterministic behavior, proper data structures, and CI discipline. **Foundation** covered configuration and data models that keep code, flags, and documentation aligned. The 2025 releases followed those tracks and turned MrDocs from a proof of concept into a tool that other teams can adopt.
@@ -56,6 +92,32 @@ I started the year with a gap analysis that compared MrDocs to other C++ documen
 
 Together, these releases executed the roadmap derived from the initial gap analysis: they **aligned** the moving parts, **closed** the most important capability gaps, and delivered a **stable foundation** that future work can extend without re-litigating fundamentals.
 
+{% mermaid %}
+%%{init: {"theme": "base", "themeVariables": {
+  "primaryColor": "#e4eee8",
+  "primaryBorderColor": "#affbd6",
+  "primaryTextColor": "#000000",
+  "lineColor": "#baf9d9",
+  "secondaryColor": "#f0eae4",
+  "tertiaryColor": "#ebeaf4",
+  "fontSize": "14px"
+}}}%%
+mindmap
+  root((MVP Evolution))
+    v0.0.3
+      Config sync
+      Shared templates
+      CI discipline
+    v0.0.4
+      Warning controls
+      Schema
+      Bootstrap
+    v0.0.5
+      Recursive docs
+      Nav refresh
+      Tooling polish
+{% endmermaid %}
+
 ## v0.0.3: Enforcing Consistency
 
 `v0.0.3` is where MrDocs stopped being a collection of one-off special cases and became a coherent system. Before this release, features landed in a single generator and drifted from the others; extraction handled only the narrowly requested pattern and crashed on nearby ones; and options were inconsistent—some hard-coded, some missing from CLI/config, with no mechanism to keep code, docs, and flags aligned.
@@ -197,6 +259,36 @@ MrDocs now ships a working MVP, but significant **foundational work** remains. T
 
 I do not know how the leadership model will evolve in 2026. The team might keep a single coordinator or move to shared stewardship. Regardless, the project only succeeds if we continue investing in **foundational capabilities**. The steps below outline the **recommendations** I believe will help keep MrDocs **sustainable over the long term**.
 
+{% mermaid %}
+%%{init: {"theme": "base", "themeVariables": {
+  "primaryColor": "#f2eadf",
+  "primaryBorderColor": "#ffe8c6",
+  "primaryTextColor": "#000000",
+  "lineColor": "#ffe8c8",
+  "secondaryColor": "#e8ebf3",
+  "tertiaryColor": "#eceaf4",
+  "fontSize": "14px"
+}}}%%
+mindmap
+  root((2026 Priorities))
+    Reflection
+      Describe symbols
+      Shared walkers
+    Metadata
+      Recursive docs
+      Stable names
+      Typed expressions
+    Extensions
+      Script helpers
+      Plugin ABI
+    Dependencies
+      Curated toolchain
+      Opt-in stubs
+    Community
+      Integration demos
+      Outreach cadence
+{% endmermaid %}
+
 ## Strategic Prioritization
 
 Aligning **priorities** is itself the highest priority. At the start of my tenure as project lead we followed a strict sequence—**gap analysis**, then an **MVP**, then a set of **priorities**—but that model exposed limitations once work began to land. The **issue tracker** does not reflect how priorities relate to each other, and as individual tickets close the priority stack does not adjust automatically. The project’s **complexity** now amplifies the risk: without a clear view of **dependencies** we can assign a high-value engineer to a task that drags several teammates into the same bottleneck, resulting in net-negative progress. Defining priorities therefore includes understanding the team’s **skills**, mapping how they **collaborate**, and making sure no one becomes a **sink** that blocks everyone else. **Alignment** across roles remains essential so the plan reflects the people who actually execute it.
@@ -211,6 +303,25 @@ The corpus keeps drifting out of sync because every important path in MrDocs dup
 
 A lightweight option would be to enforce the corpus from JSON the way we treat configuration, but the volume of metadata in AST makes that impractical. Instead, we lean on **compile-time reflection utilities** such as **Boost.Describe** and **Boost.mp11**. With those libraries we can convert the corpus to any representation, and each generator—including future **binary** or **JSON** targets—sees the same schema automatically. MrDocs can even emit the schema that powers each generator, keeping the schema, DOM, and documentation in sync. This approach also fixes the long-standing lag in the **XML generator**, where updates have historically been manual and error-prone.
 
+The following sequence diagram illustrates how reflection consolidates data flow without duplicating logic:
+
+{% mermaid %}
+sequenceDiagram
+  participant AST as Clang AST
+  participant Corpus as Typed Corpus
+  participant Traits as Reflect Traits
+  participant DOM as Corpus DOM
+  participant Generators as Generators
+  participant Clients as Integrations
+  AST->>Corpus: Extract symbols
+  Corpus->>Traits: Publish descriptors
+  Traits->>DOM: Build type-erased nodes
+  DOM->>Generators: Supply normalized schema
+  Generators->>Clients: Deliver outputs
+  Clients->>Generators: Provide feedback
+  Generators->>Traits: Request updates
+{% endmermaid %}
+
 **Process:** We can start by describing the **Symbols**, **Javadoc**, and related classes, shipping each refactor as a dedicated PR so reviews stay contained. Each description removes custom specializations, reverts to `= default` where possible, and replaces old logic with **static asserts** that enforce invariants. We generalize the main merge logic first, then update callers such as the **AST visitor** that walks `RecordTranche`, ensuring the **comments data structure** matches the new descriptions. A `MRDOCS_DESCRIBE_DERIVED` helper can enumerate derived classes so every visit routine becomes generic. Once the C++ side is described, we rebuild the lazy DOM objects on top of Describe so their types mirror the DOM layout directly.
 
 **Use cases:** Redundant non-member functions like `tag_invoke`, `operator⇔`, `toString`, and `merge` collapse into **shared implementations** that use traits unless real customization is required. New generators—binary, JSON, or otherwise—drop in with minimal code because the schema and traversal logic already exist. The XML generator stops maintaining a private representation and simply reads the described elements. We can finally standardize **naming conventions** (kebab-case or camelCase) because the schema enforces them. Generating the **Relax NG Compact** file becomes just another output produced from the same description. A metadata walker can then discover auxiliary objects and emit **DOM documentation automatically**. As a side effect of integrating Boost.mp11, we can extend the `tag_invoke` context protocol with tuple-based helpers for `mrdocs::FromValue`, further narrowing the gap between concrete and DOM objects.