DOC-6026 further tree improvements

Author: andy-stark-redis

build/render_hook_docs/DECISION_TREE_FORMAT.md

@@ -49,6 +49,7 @@ questions:
 - **`scope`** (required): Category or domain this tree applies to (e.g., `documents`, `collections`, `sequences`). Helps AI agents understand the tree's purpose and applicability.
 - **`rootQuestion`** (required): The ID of the starting question
 - **`questions`** (required): Object containing all questions, keyed by ID
+- **`indentWidth`** (optional): Horizontal spacing in pixels between parent and child nodes. Default: 40. Use smaller values (e.g., 20-30) for deeply nested trees to reduce overall width. This is a rendering preference and does not affect the semantic metadata.
 
 ### Question Object
 
@@ -138,6 +139,7 @@ scope: documents
 8. **Add sentiment for suitability trees**: If your tree determines whether something is suitable (not just choosing between options), use `sentiment: "positive"` and `sentiment: "negative"` to provide visual feedback
 9. **Be consistent with sentiment**: In a suitability tree, ensure all positive outcomes have `sentiment: "positive"` and all negative outcomes have `sentiment: "negative"` for clarity
 10. **Control answer order**: The order of `yes` and `no` in the YAML controls the visual layout. For early rejection patterns, put `no` first so negative outcomes appear on the left side of the diagram
+11. **Adjust indent width for deeply nested trees**: If your tree has many levels and becomes too wide, use `indentWidth="25"` (or lower) in the code block fence to reduce horizontal spacing between parent and child nodes
 
 ## Example: Redis Data Type Selection
 

build/render_hook_docs/DECISION_TREE_IMPLEMENTATION_NOTES.md

@@ -197,3 +197,60 @@ answerLabel = item.answer || 'Yes';  // Use stored value, not position
 
 **Key Insight**: YAML object key order is preserved in JavaScript (since ES2015), and we now respect both the order AND the actual answer values, making the layout fully author-controlled.
 
+## 13. Configurable Indent Width for Deeply Nested Trees
+
+**Problem**: Deeply nested decision trees (with many levels of questions) can become too wide to fit on the page, requiring horizontal scrolling.
+
+**Solution**: Added optional `indentWidth` parameter to the YAML root object that controls the horizontal spacing between parent and child nodes:
+
+```yaml
+id: when-to-use-rdi
+scope: rdi
+indentWidth: 25  # Reduce from default 40 to make tree narrower
+rootQuestion: cacheTarget
+questions:
+  # ...
+```
+
+**Implementation**:
+In `renderDecisionTree()`, the indent width is read from `treeData.indentWidth` with a sensible default:
+```javascript
+const indentWidth = treeData.indentWidth ? parseInt(treeData.indentWidth) : 40;
+```
+
+**Design Rationale**: While `indentWidth` is a rendering preference, it's included in the YAML because:
+1. Hugo's Goldmark attribute parsing doesn't reliably expose custom attributes from the code block info string to the render hook
+2. Including it in the YAML keeps all tree configuration in one place
+3. AI agents can still access the semantic metadata (id, scope, questions) separately from rendering preferences
+
+**Benefit**: Authors can now control tree width by adjusting `indentWidth`:
+- Default (40): Comfortable spacing for shallow trees
+- Reduced (20-30): Compact layout for deeply nested trees
+- The SVG width is calculated as: `leftMargin + (maxDepth + 1) * indentWidth + maxBoxWidth + 40`
+
+**Recommendation**: For trees with 8+ levels of nesting, try `indentWidth: 25` or lower to keep the diagram readable without horizontal scrolling.
+
+## 14. Improved Label Visibility with Reduced Indent Width
+
+**Problem**: When using reduced `indentWidth` values, the Yes/No labels on the connecting lines were being covered by the node boxes they referred to.
+
+**Solution**:
+1. Increased the vertical offset of labels from `y + 10` to `y + 16` pixels
+2. Added a white background rectangle behind each label to ensure visibility even when overlapping with boxes
+
+**Implementation**:
+```javascript
+const labelY = y + 16;  // Increased offset
+
+// Add white background rectangle behind label
+const labelBg = document.createElementNS('http://www.w3.org/2000/svg', 'rect');
+labelBg.setAttribute('x', labelX - 12);
+labelBg.setAttribute('y', labelY - 9);
+labelBg.setAttribute('width', '24');
+labelBg.setAttribute('height', '12');
+labelBg.setAttribute('fill', 'white');
+svg.appendChild(labelBg);
+```
+
+**Benefit**: Labels remain readable regardless of indent width or tree density.
+

content/integrate/redis-data-integration/when-to-use.md

@@ -71,6 +71,7 @@ Use the decision tree below to determine whether RDI is a good fit for your arch
 ```decision-tree {id="when-to-use-rdi"}
 id: when-to-use-rdi
 scope: rdi
+indentWidth: 25
 rootQuestion: cacheTarget
 questions:
     cacheTarget:
@@ -82,7 +83,7 @@ questions:
             no:
                 value: "No"
                 outcome:
-                    label: "RDI is not necessary - you don't need Redis as a cache"
+                    label: "RDI only works with Redis as the target database"
                     id: noRedisCache
                     sentiment: "negative"
             yes:
@@ -97,39 +98,24 @@ questions:
             no:
                 value: "No"
                 outcome:
-                    label: "RDI won't work - you need a single source database"
+                    label: "RDI won't work with multiple source databases"
                     id: multipleSourcesOrActiveActive
                     sentiment: "negative"
             yes:
                 value: "Yes"
                 nextQuestion: systemOfRecord
     systemOfRecord:
         text: |
-            Is the source database your system of record?
+            Does your app always *write* to the source database and not to Redis?
         whyAsk: |
             RDI requires the source database to be the authoritative source of truth. If your app writes to Redis first, RDI won't work.
         answers:
             no:
                 value: "No"
                 outcome:
-                    label: "RDI won't work - the source database must be the system of record"
+                    label: "RDI doesn't support syncing data from Redis back to the source database"
                     id: notSystemOfRecord
                     sentiment: "negative"
-            yes:
-                value: "Yes"
-                nextQuestion: appWritesToDb
-    appWritesToDb:
-        text: |
-            Does your app always write its data to the source database?
-        whyAsk: |
-            RDI requires the app to write to the source database first. If your app writes to Redis first, RDI cannot maintain consistency.
-        answers:
-            no:
-                value: "No"
-                outcome:
-                    label: "RDI won't work - your app must write to the source database"
-                    id: appWritesToRedis
-                    sentiment: "negative"
             yes:
                 value: "Yes"
                 nextQuestion: consistency
@@ -142,7 +128,7 @@ questions:
             no:
                 value: "No"
                 outcome:
-                    label: "RDI is not suitable - you need immediate cache consistency"
+                    label: "RDI does not provide immediate cache consistency"
                     id: needsImmediate
                     sentiment: "negative"
             yes:
@@ -195,33 +181,33 @@ questions:
                 nextQuestion: dataSize
     dataSize:
         text: |
-            Is your total data size not larger than 100GB?
+            Is your total data size smaller than 100GB?
         whyAsk: |
             RDI has practical limits on the total data size it can manage. Very large datasets may exceed these limits.
         answers:
             no:
                 value: "No"
                 outcome:
-                    label: "RDI may not be suitable - your data set is too large"
+                    label: "RDI may not be suitable - your data set is probably too large"
                     id: dataTooLarge
                     sentiment: "negative"
             yes:
                 value: "Yes"
                 nextQuestion: joins
     joins:
         text: |
-            Do you not need to perform join operations on data from several tables into a nested Redis JSON object?
+            Do you need to perform join operations on data from several tables into a nested Redis JSON object?
         whyAsk: |
             RDI has limitations with complex join operations. If you need to combine data from multiple tables into nested structures, you may need custom transformations.
         answers:
-            no:
-                value: "No"
+            yes:
+                value: "Yes"
                 outcome:
                     label: "RDI may not be suitable - complex joins are not well supported"
                     id: complexJoins
                     sentiment: "negative"
-            yes:
-                value: "Yes"
+            no:
+                value: "No"
                 nextQuestion: transformations
     transformations:
         text: |
@@ -232,22 +218,23 @@ questions:
             no:
                 value: "No"
                 outcome:
-                    label: "RDI may not be suitable - required transformations are not supported"
+                    label: "RDI may not be able to perform the required data transformations"
                     id: unsupportedTransformations
                     sentiment: "negative"
             yes:
                 value: "Yes"
                 nextQuestion: adminReview
     adminReview:
         text: |
-            Has your database administrator reviewed and confirmed that RDI's requirements for the source database are acceptable?
+            Has your database administrator reviewed RDI's requirements for the source database
+            and confirmed they are acceptable?
         whyAsk: |
             RDI has specific requirements for the source database (binary logging, permissions, etc.). Your DBA must confirm these are acceptable before proceeding.
         answers:
             no:
                 value: "No"
                 outcome:
-                    label: "RDI is not suitable - database administrator has rejected RDI's requirements"
+                    label: "RDI requirements for the source database can't be met"
                     id: adminRejected
                     sentiment: "negative"
             yes:

static/js/decision-tree.js

@@ -69,7 +69,7 @@
     const items = [];
     const visited = new Set();
 
-    function traverse(nodeId, depth) {
+    function traverse(nodeId, depth, parentAnswer = null) {
       if (visited.has(nodeId)) return;
       visited.add(nodeId);
 
@@ -81,7 +81,8 @@
         depth: depth,
         type: 'question',
         text: question.text || '',
-        whyAsk: question.whyAsk || ''
+        whyAsk: question.whyAsk || '',
+        answer: parentAnswer  // Store the answer that led to this question
       });
 
       if (question.answers) {
@@ -92,15 +93,19 @@
         answerKeys.forEach(answerKey => {
           const answer = question.answers[answerKey];
           if (answer) {
+            // Store the answer value for use in tree line labels
+            const answerValue = answer.value || answerKey.charAt(0).toUpperCase() + answerKey.slice(1);
+
             if (answer.nextQuestion) {
-              traverse(answer.nextQuestion, depth + 1);
+              // Traverse to next question, passing the answer value
+              traverse(answer.nextQuestion, depth + 1, answerValue);
             } else if (answer.outcome) {
               items.push({
                 id: answer.outcome.id,
                 depth: depth + 1,
                 type: 'outcome',
                 text: answer.outcome.label || '',
-                answer: answer.value || answerKey.charAt(0).toUpperCase() + answerKey.slice(1),
+                answer: answerValue,
                 sentiment: answer.outcome.sentiment || null
               });
             }
@@ -147,7 +152,8 @@
     const charWidth = 8;
     const leftMargin = 20;
     const topMargin = 10;
-    const indentWidth = 40; // Increased from 24 for wider indent
+    // Allow indentWidth to be customized via YAML, default to 40
+    const indentWidth = treeData.indentWidth ? parseInt(treeData.indentWidth) : 40;
     const boxPadding = 12; // Increased from 8 for more padding
     const maxBoxWidth = 420; // Increased to accommodate longer questions
     const maxCharsPerLine = Math.floor(maxBoxWidth / charWidth);
@@ -305,9 +311,20 @@
       hline.setAttribute('stroke-width', '1');
       svg.appendChild(hline);
 
-      // Add answer label on the horizontal line, positioned below it to avoid boxes
-      const labelX = connectorX + (boxX + hlineExtension - connectorX) / 2;
-      const labelY = y + 10;
+      // Add answer label on the horizontal line, positioned to the left to avoid box overlap
+      // Position label closer to parent box, shifted left by the indent amount
+      const labelX = connectorX + (indentWidth * 0.3);  // Position at 30% of the way across
+      const labelY = y + 16;  // Increased offset to avoid box overlap
+
+      // Add white background rectangle behind label for visibility
+      const labelBg = document.createElementNS('http://www.w3.org/2000/svg', 'rect');
+      labelBg.setAttribute('x', labelX - 12);
+      labelBg.setAttribute('y', labelY - 9);
+      labelBg.setAttribute('width', '24');
+      labelBg.setAttribute('height', '12');
+      labelBg.setAttribute('fill', 'white');
+      labelBg.setAttribute('stroke', 'none');
+      svg.appendChild(labelBg);
 
       const label = document.createElementNS('http://www.w3.org/2000/svg', 'text');
       label.setAttribute('x', labelX);