internal/planning/docs-improvement/02-pr-1813-comparison.md
Date: September 30, 2025 PR Reference: #1813 - Comprehensive documentation improvements Merged: September 23, 2025 by Justin Gordon
PR #1813 made significant progress on documentation improvements, addressing many surface-level issues. However, the fundamental information architecture problems remain unresolved. This document compares what was fixed against the problems identified in 01-problem-analysis.md.
Problem Addressed: Section 2.1 - Missing fast onboarding path
What Was Done:
docs/quick-start/README.md (212 lines)Impact:
Remaining Gaps:
Problem Addressed: Section 5.3 - Scattered troubleshooting
What Was Done:
docs/troubleshooting/README.md (304 lines)Impact:
Quality: Strong execution. This addresses the troubleshooting fragmentation well.
Problem Addressed: Section 1.2 - Multiple conflicting entry points
What Was Done:
docs/README.md (172 lines)Impact:
Remaining Issues:
README.md, docs/README.md, docs/home.md, docs/getting-started.md, docs/quick-start/README.mdProblem Addressed: Section 4.1 - Link management risk
What Was Done:
Impact:
Quality: Excellent technical improvement with future-proofing.
Problem Addressed: Section 2.3 - Inconsistent prerequisites
What Was Done:
Impact:
Problem Addressed: Section 3.4 - Inconsistent formatting
What Was Done:
Impact:
Quality: Good improvement, though not comprehensive across all docs.
Problem Addressed: (Not in our analysis - bonus improvement)
What Was Done:
AI_AGENT_INSTRUCTIONS.mdImpact:
Problem Addressed: Section 2.1 - Outdated patterns
What Was Done:
Impact:
Original Problem: Section 1.1 - Unclear category hierarchy
Current State:
The 11-category structure in gatsby-node.js:31-44 was not changed:
const reactOnRailsDocsFoldersOrder = [
firstCategory,
'Guides', // Still 18+ diverse topics
'Rails',
'Javascript',
'Additional details', // Still a catch-all
'Deployment',
'React on rails pro',
'Api',
'Misc', // Still a catch-all
'Contributor info', // Still in main nav
'Testimonials', // Still in main nav
'Outdated', // Still visible!
];
Why This Wasn't Fixed:
PR #1813 focused on content improvements within existing structure, not restructuring the categories themselves. This is understandable as restructuring requires website code changes in sc-website repo.
Impact:
Evidence:
From 01-problem-analysis.md Section 1.1, all issues remain:
Original Problem: Section 1.2 - Four conflicting starting points
Current State After PR #1813:
README.md - Main project README (now better, but still project-level)docs/README.md - New documentation hub (172 lines, comprehensive navigation)docs/home.md - Still exists (29 lines, just links) - Why?docs/getting-started.md - Enhanced (254 lines) but still tries to be everythingdocs/quick-start/README.md - NEW (212 lines) - Great, but another entry pointCurrent User Experience:
A new user might land on:
README.md → links to docs/docs/home.md? docs/README.md? getting-started.md?docs/quick-start/README.mdCross-References Create Circular Navigation:
From docs/README.md:9-11:
**→ [15-Minute Quick Start Guide](./quick-start/README.md)**
Already have Rails + Shakapacker? **→ [Add to existing app guide](./guides/installation-into-an-existing-rails-app.md)**
From docs/getting-started.md:3:
> **💡 Looking for the fastest way to get started?** Try our **[15-Minute Quick Start Guide](./quick-start/README.md)** instead.
Questions:
getting-started.md first?docs/home.md for? (Still unexplained)Why This Wasn't Fully Fixed: PR #1813 improved coordination between entry points but didn't consolidate them. Each doc now cross-references others better, but the fundamental question remains: "Where do I actually start?"
Impact:
Original Problem: Section 2.1 - Missing conceptual foundations
Current State:
Example: Server-Side Rendering
From updated docs/getting-started.md:93-97 (still in PR #1813):
- **Server-Side Rendering**: Your React component is first rendered into HTML on the server. Use the **prerender** option:
```erb
<%= react_component("HelloWorld", props: @some_props, prerender: true) %>
**Still Missing:**
- ❌ What is SSR conceptually?
- ❌ Why does it matter? (SEO, performance, UX)
- ❌ What's the tradeoff? (complexity vs. benefits)
- ❌ When should I use it vs. not?
**Pattern Persists:**
Documentation still follows "here's the feature → here's the syntax" rather than "here's the problem → here's how this solves it → here's how to use it."
**Why This Wasn't Fixed:**
Foundational concept explanations require new content, not just reorganization. PR #1813 focused on improving existing content flow, not adding conceptual deep-dives.
**Impact:**
- ❌ Beginners still need to understand webpack, bundling, SSR, render functions without explicit teaching
- ❌ Copy-paste without understanding continues
- ❌ Debugging harder for users who don't grasp concepts
**What Would Fix This:**
New conceptual guides in a "Core Concepts" section:
- "Understanding Server-Side Rendering"
- "How Bundling Works in React on Rails"
- "Component Registration Explained"
- "Props and RailsContext Deep Dive"
---
### 4. Installation Still Scattered ⚠️
**Original Problem:** Section 2.2 - Installation across multiple docs
**Current State After PR #1813:**
**Improved:**
- ✅ Quick start now provides fast installation path
- ✅ `getting-started.md` enhanced with clearer steps
- ✅ Version requirements consistent
**Still Scattered:**
1. **`docs/quick-start/README.md`** - Fast 15-minute path
2. **`docs/getting-started.md:38-76`** - "Basic Installation" section
3. **`docs/guides/installation-into-an-existing-rails-app.md`** - Detailed existing app guide
4. **`docs/guides/tutorial.md`** - Tutorial-based installation
5. **Root `README.md`** - Quick install commands
**Questions for Users:**
- Which installation guide do I follow?
- Are they all saying the same thing?
- When do I use quick-start vs. installation-into-existing-app?
**Why This Wasn't Fully Fixed:**
Different user journeys legitimately need different installation instructions:
- Blank slate → Quick start
- Existing app → Detailed integration guide
- Learning journey → Tutorial
The issue is these aren't clearly **differentiated and signposted**.
**Impact:**
- ⚠️ Better coordination but still multiple sources
- ✅ Each guide improved individually
- ❌ User still has to decide which path to follow
- ❌ Risk of conflicting instructions
**What Would Fix This:**
Clear decision tree on main docs page:
Are you... ├─ Starting a brand new Rails app? → Quick Start ├─ Adding React to existing Rails app? → Integration Guide └─ Learning React on Rails deeply? → Tutorial
Then ensure all three paths are **internally consistent** in their steps.
---
### 5. No "Why React on Rails?" Introduction ❌
**Original Problem:** Section 5.1 - Missing value proposition
**Current State:**
Still no clear "Why React on Rails?" page.
**What Exists:**
- `docs/guides/react-on-rails-overview.md` - Technical overview, not value proposition
- `docs/guides/how-react-on-rails-works.md` - Architecture explanation
**Still Missing:**
1. **Problem Statement:**
- Why integrate React with Rails?
- What pain points does this solve?
2. **Comparison with Alternatives:**
- vs. plain Rails views + Hotwire
- vs. separate React SPA
- vs. react-rails gem
- vs. Inertia.js
3. **When to Use / When Not to Use:**
- Best fit use cases
- When to choose something else
4. **Decision Framework:**
- Help teams evaluate if React on Rails is right for them
**Why This Wasn't Fixed:**
PR #1813 focused on improving **how-to** documentation for users who've already decided to use React on Rails. The "why" content is a different type of writing (persuasive/educational vs. instructional).
**Impact:**
- ❌ Developers can't make informed architectural decisions
- ❌ No clear pitch for managers/stakeholders
- ❌ Evaluation takes longer (have to read through implementation docs to infer value)
- ❌ Harder to advocate internally for adoption
**What Would Fix This:**
New page: `docs/introduction.md` or `docs/why-react-on-rails.md`:
- Problem: Building interactive UIs in Rails
- Solutions overview (spectrum from Hotwire to SPA)
- Where React on Rails fits
- Key benefits (SSR, component reuse, Rails integration, developer experience)
- Tradeoffs (complexity, learning curve)
- Who should use it / who shouldn't
---
### 6. No Progressive Disclosure ❌
**Original Problem:** Section 3.1 - Flat structure, no difficulty levels
**Current State:**
**Small Improvement in `docs/README.md`:**
```markdown
### 🔰 **Beginner Path**
1. Quick Start
2. Core Concepts
3. Tutorial
### ⚡ **Experienced Developer Path**
- Installation Guide
- API Reference
- Advanced Features
Better, but still limited:
In Sidebar Navigation (not changed by PR #1813): The Gatsby sidebar still shows all 11 categories with all docs visible at once:
Guides (18+ files, all visible)
├─ Tutorial
├─ Installation
├─ Configuration
├─ Streaming SSR (advanced!)
├─ How to conditionally render (advanced!)
└─ ...all mixed together
Why This Wasn't Fixed: Progressive disclosure requires restructuring the category system and potentially duplicating docs into "Basic" and "Advanced" sections. PR #1813 worked within existing structure.
Impact:
docs/README.md helps with signpostingWhat Would Fix This:
Restructure categories in gatsby-node.js:
const reactOnRailsDocsFoldersOrder = [
'Getting Started', // Quick start, installation, first component
'Core Concepts', // SSR, bundling, registration, props
'Building Features', // Common patterns, real-world examples
'Advanced', // Streaming SSR, device-specific rendering, custom configs
'API Reference', // View helpers, JS API, configuration
'Deployment', // Production setup
'Troubleshooting', // (already good)
];
Original Problem: Section 3.2 - Reference vs. learning content not separated
Current State:
Slight Improvement:
docs/api/ folder exists with 3 filesdocs/README.md has "API Reference" sectionStill Mixed:
From docs/getting-started.md:
react_component)react_component_hash (API reference)From docs/guides/configuration.md (316 lines):
Pattern: Learning guides still contain API reference information inline, rather than linking to centralized API docs.
Why This Wasn't Fully Fixed: Separating API reference from guides requires:
PR #1813 improved existing docs but didn't reorganize this structure.
Impact:
What Would Fix This:
In Guides (learning):
## Using react_component
The `react_component` helper renders React components in Rails views.
**Basic usage:**
<%= react_component("MyComponent", props: { name: "World" }) %>
For all options and parameters, see [react_component API Reference](/api/view-helpers-api#react_component).
In API Reference (complete listing):
# react_component API
## Syntax
<%= react_component(component_name, options) %>
## Parameters
| Parameter | Type | Default | Description |
| component_name | String | required | ... |
| props | Hash | {} | ... |
| prerender | Boolean | false | Enable SSR |
| trace | Boolean | false | ... |
[Complete table with ALL options]
Original Problem: Section 1.3 - Contributor docs mixed with user docs
Current State: Completely unchanged. All these still in main navigation:
contributor-info/ folder - 5 files:
linters.mdcoding-agents-guide.md (newly created in PR #1813)errors-with-hooks.mdgenerator-testing.mdreleasing.mdpull-requests.mdPlanning documents:
docs/planning/DOCUMENTATION_IMPROVEMENT_PLAN.md (created in PR #1813)docs/planning/DOCS_PR_SUMMARY.md (created in PR #1813)Root-level internal docs:
docs/MONOREPO_MERGER_PLAN.mddocs/DIRECTORY_LICENSING.mdWhy This Wasn't Fixed:
PR #1813 was content-focused, not navigation-focused. Hiding these requires changes to website build (gatsby-node.js) to exclude certain paths.
Impact:
What Would Fix This:
In sc-website/gatsby-node.js, filter out internal directories:
docs: allFile(
filter: {
dir: { regex: "/^.*/gatsby-source-git/.*$/" }
extension: { in: ["md", "mdx"] }
// Add this:
relativePath: {
regex: "/^(?!.*\/(contributor-info|planning|MONOREPO|DIRECTORY).*$).*/"
}
}
)
Then create separate /contributing/ section for contributor docs.
Original Problem: Section 3.3 - Marketing content in docs
Current State: Completely unchanged.
From gatsby-node.js:41-42:
"Testimonials",
"Outdated",
Still the last two categories in technical documentation navigation.
Why This Wasn't Fixed: Same as #8 - navigation restructuring not in scope of PR #1813.
Impact:
What Would Fix This:
reactOnRailsDocsFoldersOrderOriginal Problem: Section 1.4 - Deprecated docs in main nav
Current State: Completely unchanged.
From gatsby-node.js:43:
"Outdated", // ← Still last category!
Still visible as the final category in navigation.
Why This Wasn't Fixed: Navigation restructuring not in scope.
Impact:
What Would Fix This:
reactOnRailsDocsFoldersOrderv15.shakacode.com/docs)| Problem Area | Severity (Before) | Status After PR #1813 | Priority |
|---|---|---|---|
| 1. Quick start missing | 🔴 Critical | ✅ FIXED | - |
| 2. Troubleshooting scattered | 🟡 Medium | ✅ FIXED | - |
| 3. Broken links | 🟡 Medium | ✅ FIXED | - |
| 4. Version requirements inconsistent | 🟡 Medium | ✅ FIXED | - |
| 5. Visual formatting poor | 🟡 Medium | ✅ IMPROVED | - |
| 6. Content outdated | 🟡 Medium | ✅ FIXED | - |
| 7. Information architecture unclear | 🔴 Critical | ❌ UNRESOLVED | 🔥 High |
| 8. Multiple entry points | 🔴 Critical | ⚠️ PARTIAL | 🔥 High |
| 9. Concepts not explained | 🔴 Critical | ❌ UNRESOLVED | 🔥 High |
| 10. No "Why" introduction | 🔴 Critical | ❌ UNRESOLVED | 🔥 High |
| 11. Installation scattered | 🟡 Medium | ⚠️ IMPROVED | Medium |
| 12. No progressive disclosure | 🟡 Medium | ⚠️ PARTIAL | Medium |
| 13. API mixed with guides | 🟡 Medium | ⚠️ PARTIAL | Medium |
| 14. Internal docs visible | 🟠 Low | ❌ UNRESOLVED | Low |
| 15. Testimonials in docs | 🟠 Low | ❌ UNRESOLVED | Low |
| 16. "Outdated" visible | 🟠 Low | ❌ UNRESOLVED | Low |
Legend:
Strengths:
Type of Improvements:
What It Didn't Do:
These require changes to both react_on_rails repo and sc-website repo:
Information Architecture Redesign
sc-website/gatsby-node.js:31-44Entry Point Consolidation
docs/home.md, docs/README.md, docs/getting-started.mdProgressive Disclosure System
gatsby-node.js category order, frontmatter in docsThese only require changes to react_on_rails repo:
Conceptual Guides
docs/concepts/*.mdValue Proposition Introduction
docs/introduction.mdAPI Reference Consolidation
docs/api/*.md + remove duplication from guidesInstallation Decision Tree
Search and Metadata
Week 1-2: Information Architecture Redesign
Reasoning: Even if we add more great content (like PR #1813 did), users still can't find it easily due to poor IA. Fix the structure first, then add content.
Week 3-4: Conceptual Guides
Month 2: Polish and Consistency
PR #1813 was excellent tactical work that fixed many immediate issues and created valuable new resources (quick start, troubleshooting). The new content is well-written and user-focused.
However, the fundamental strategic problems remain: unclear information architecture, confusing entry points, missing conceptual foundations, and no clear value proposition.
Next steps should focus on structural changes (IA redesign, entry point consolidation) before adding more content. Otherwise, we risk creating more great content that users still can't navigate effectively.
Analogy: PR #1813 renovated the rooms in the house (new furniture, fresh paint, better lighting). But users still can't find the rooms because the floor plan is confusing and there are too many front doors.
We need to: