internal/planning/docs-improvement/01-problem-analysis.md
Date: September 30, 2025 Analyst: Ihab Goal: Identify specific issues preventing users from having a smooth, professional documentation experience
Problem: The current 11-category structure lacks clear hierarchy and logical grouping.
Current Categories (defined in gatsby-node.js:31-44):
const reactOnRailsDocsFoldersOrder = [
firstCategory, // Root-level files
'Guides', // 18+ diverse topics
'Rails', // Rails-specific integration
'Javascript', // JS/webpack/bundling topics
'Additional details', // Catch-all category
'Deployment', // Production setup
'React on rails pro', // Pro version features
'Api', // API reference
'Misc', // Another catch-all
'Contributor info', // Developer-facing docs
'Testimonials', // Marketing content
'Outdated', // Deprecated docs
];
Specific Issues:
"Additional details" - Vague catch-all containing:
migrating-from-react-rails.md (migration guide)generator-details.md (technical reference)recommended-project-structure.md (best practices)updating-dependencies.md (maintenance)"Misc" - Another unclear bucket with:
tips.md - General guidance (should be in guides)doctrine.md - Philosophy/principles (should be in introduction)style.md - Code style guide (contributor docs)articles.md - External resources (should be separate section)"Guides" is too broad - Contains 18+ files ranging from:
installation-into-an-existing-rails-app.md)tutorial.md)configuration.md)streaming-server-rendering.md)how-to-conditionally-server-render-based-on-device-type.md)Impact:
Source Files:
/home/ihab/ihab/work/shakacode/sc-website/gatsby-node.js:31-44/home/ihab/ihab/work/shakacode/sc-website/src/styleguide/page-components/DocArticle/DocSidebar.tsx:178-253Problem: Four different "starting point" documents create confusion about where to begin.
Entry Points Found:
docs/README.md (173 lines)
docs/home.md (29 lines)
docs/getting-started.md (254 lines)
docs/quick-start/README.md (location referenced but not yet examined)
Confusion Points:
From 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 getting-started.md:3-11:
> **š” Looking for the fastest way to get started?** Try our **[15-Minute Quick Start Guide](./quick-start/README.md)** instead.
## Choose Your Starting Point
...
### š **New to React on Rails?**
**ā [15-Minute Quick Start](./quick-start/README.md)** - Get your first component working fast
Impact:
Problem: Navigation includes docs meant only for contributors, not end users.
Contributor Docs in Main Navigation:
contributor-info/ folder - 5 files:
linters.md - Linting setup for contributorscoding-agents-guide.md - Guide for AI coding assistantserrors-with-hooks.md - Git hooks troubleshootinggenerator-testing.md - Testing generators during developmentreleasing.md - Release process for maintainerspull-requests.md - PR guidelinesPlanning documents visible:
docs/planning/DOCUMENTATION_IMPROVEMENT_PLAN.mddocs/planning/DOCS_PR_SUMMARY.mdRoot-level internal docs:
docs/MONOREPO_MERGER_PLAN.md (32KB)docs/MONOREPO_MERGER_PLAN_REF.mddocs/DIRECTORY_LICENSING.mdImpact:
Evidence:
From gatsby-node.js:185-194, the build system includes ALL markdown files:
result.data.docs.edges.forEach(({ node: doc }) => {
const [, relativePath] = doc.dir.split('gatsby-source-git/');
const [repoName, , folder] = relativePath.split('/');
// Creates pages for ALL .md files in docs/
});
Problem: A category called "Outdated" is visible in primary navigation.
Outdated Folder Contents:
docs/outdated/deferred-rendering.mddocs/outdated/webpack-v1-notes.mddocs/outdated/rails3.mddocs/outdated/rails-assets.mddocs/outdated/rails-assets-relative-paths.mdCurrent Treatment:
From gatsby-node.js:31-44, "Outdated" is the last category but still included:
const reactOnRailsDocsFoldersOrder = [
// ... other categories
'Outdated', // ā Still in navigation!
];
Issues:
Better Practices (from competitors):
nextjs.org/docs/pages/... for old Pages Router)guides.rubyonrails.org/v7.0/...)Impact:
Problem: Documentation jumps into implementation details without explaining foundational concepts.
Example 1: Server-Side Rendering (SSR)
From getting-started.md:93-97:
- **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) %>
**Missing Context:**
- What is SSR and why does it matter?
- What's the difference between client-side and server-side rendering?
- When should I use `prerender: true` vs not using it?
- What are the performance implications?
- What are the limitations?
Users see `prerender: true` without understanding the "why" behind it.
---
**Example 2: Auto-Bundling**
From `getting-started.md:101-138`:
```markdown
## Auto-Bundling (includes Auto-Registration)
React on Rails supports **Auto-Bundling**, which automatically creates the webpack bundle _and_ registers your React components. This means you don't have to manually configure packs or call `ReactOnRails.register(...)`.
Missing Context:
The comparison between manual and auto-bundling helps, but assumes user understands webpack concepts.
Example 3: Render Functions
From getting-started.md:178-204:
## Specifying Your React Components
You have two ways to specify your React components. You can either register the React component (either function or class component) directly, or you can create a function that returns a React component, which we using the name of a "render-function".
Missing Context:
Pattern Observed:
The docs follow a "reference manual" pattern:
Instead of a "learning guide" pattern:
Impact:
Problem: Installation steps are fragmented across multiple documents without clear ownership.
Installation Information Locations:
getting-started.md:38-76 - "Basic Installation"
guides/installation-into-an-existing-rails-app.md - Full guide
quick-start/README.md - Quick installation
README.md:44 - Installation link in table:
| **Add React to existing Rails app** | [Installation Guide](./guides/installation-into-an-existing-rails-app.md) |
guides/tutorial.md - Tutorial installation
Inconsistencies:
From getting-started.md:50-56:
bundle add react_on_rails --version=16.0.0 --strict
# Commit this to git (or else you cannot run the generator in the next step unless you pass the option `--ignore-warnings`).
Questions raised:
--ignore-warnings?These concerns aren't addressed in context.
Impact:
Problem: Documentation assumes knowledge that beginners may not have.
Assumed Knowledge Examples:
1. Shakapacker (critical dependency)
From getting-started.md:36:
> **Don't have Shakapacker?** It's the modern replacement for Webpacker and required for React on Rails.
Issues:
2. Webpack Configuration
Multiple references to webpack throughout docs assume user understanding:
docs/guides/webpack-configuration.md - Entire guide about webpackdocs/javascript/webpack.md - Another webpack guideNo explanation of:
3. Rails Asset Pipeline
From getting-started.md:82-83:
- Configure `config/initializers/react_on_rails.rb`. You can adjust some necessary settings and defaults.
- Configure `config/shakapacker.yml`. If you used the generator and the default Shakapacker setup, you don't need to touch this file.
Assumptions:
4. Node.js Ecosystem
From getting-started.md:34:
ā
**Node.js 18+**
Missing information:
Impact:
Problem: All information presented at once without difficulty levels or learning paths.
Current Structure (Flat):
From README.md:52-79, the "Complete Documentation" section lists everything:
## š Complete Documentation
### Core Guides
- Getting Started
- Tutorial
- Configuration
- View Helpers
### Features
- Server-Side Rendering
- Auto-Bundling
- Redux Integration
- React Router
- Internationalization
### Development
- Hot Module Replacement
- Testing
- Debugging
### Deployment & Performance
- Deployment
- Performance
- Bundle Optimization
Issues:
Example of Confusion:
A beginner might click "Streaming Server Rendering" (advanced) before understanding basic "Server-Side Rendering" (fundamental).
From the docs structure:
docs/guides/react-server-rendering.md - Basic SSRdocs/guides/streaming-server-rendering.md - Advanced SSRBetter Pattern (from competitors):
Next.js Approach:
Getting Started (15 min)
āāā Installation
āāā Project Structure
āāā Your First Page
Building Your Application
āāā Routing
āāā Data Fetching
āāā Rendering
āāā Styling
[Much later...]
Advanced Features
āāā Streaming
āāā Server Actions
āāā Partial Prerendering
Clear progression with time estimates and prerequisites.
TanStack Router Approach:
š° Quick Start
š Guide (Basics)
š Guide (Advanced)
š API Reference
Visual indicators show learning level.
React on Rails Current Experience:
A user could accidentally read in this order:
Because all are in "Guides" with alphabetical ordering.
Impact:
Problem: Reference documentation not clearly separated from learning guides.
Current "API" Category:
From docs/api/ folder:
README.md - API overviewview-helpers-api.md - react_component helper referenceredux-store-api.md - Redux store APIjavascript-api.md - JavaScript API referenceBUT, API information also appears in:
getting-started.md:86-90 - Shows react_component usage:<%= react_component("HelloWorld", props: @some_props) %>
getting-started.md:206-222 - Documents react_component_hash:## react_component_hash for Render-Functions
Another reason to use a Render-Function is that sometimes in server rendering, specifically with React Router, you need to return the result of calling ReactDOMServer.renderToString(element).
guides/configuration.md - Config API referenceguides/render-functions-and-railscontext.md - API for render functionsProblems:
Example of Confusion:
User wants to know all options for react_component helper:
getting-started.md?api/view-helpers-api.md?Better Pattern:
Guides (Learning):
# Server-Side Rendering Guide
Learn how to render React components on the server for better performance and SEO.
## When to Use SSR
[Conceptual explanation...]
## Basic Example
[Simple working example...]
## Common Patterns
[Real-world use cases...]
š See full API: [react_component API Reference](/api/view-helpers-api)
API Reference (Looking up specifics):
# react_component API Reference
Quick reference for all options and parameters.
## Syntax
<%= react_component(component_name, options) %>
## Parameters
### component_name (String, required)
The name of your registered React component.
### options (Hash, optional)
| Option | Type | Default | Description |
| --------- | ------- | ------- | ---------------------------- |
| props | Hash | {} | Data to pass to component |
| prerender | Boolean | false | Enable server-side rendering |
| trace | Boolean | false | Enable render tracing |
[Complete table of all options...]
## Examples
[Brief examples for quick reference...]
š Learn more: [Server-Side Rendering Guide](/guides/ssr)
Impact:
Problem: Marketing content mixed with technical documentation creates unprofessional impression.
Current Structure:
From gatsby-node.js:41-42:
"Testimonials",
"Outdated",
"Testimonials" is a top-level category in the technical documentation.
Testimonials Folder Contents:
docs/testimonials/testimonials.md - List of testimonialsdocs/testimonials/hvmn.md - HVMN case studydocs/testimonials/resortpass.md - ResortPass case studyIssues:
Where Users Expect Testimonials:
Comparison with Competitors:
Next.js:
nextjs.org/docsnextjs.org/showcaseRails Guides:
guides.rubyonrails.orgrubyonrails.org/ (marketing site)TanStack:
[tanstack.com/router/latest/docs](https://tanstack.com/router/latest/docs/framework/react/overview)What to Do with Testimonials:
Impact:
Problem: Documentation files vary wildly in length, detail, and writing style without clear purpose differentiation.
Examples:
1. Extremely Short Docs:
docs/home.md - 29 lines:
# React on Rails
## Details
1. [Overview](./guides/react-on-rails-overview.md)
1. [Getting Started](./getting-started.md)
...
Just a list of links. Why does this exist separately from README?
2. Extremely Long Docs:
docs/getting-started.md - 254 lines
Tries to be everything: tutorial, reference, guide, and quickstart.
docs/README.md - 173 lines
Tries to be landing page, navigation, and TOC all at once.
3. Unclear Purpose:
docs/javascript/troubleshooting-build-errors.md vs.
docs/javascript/troubleshooting-when-using-shakapacker.md vs.
docs/troubleshooting/README.md
Three troubleshooting docs - when do I use which one?
docs/guides/webpack-configuration.md vs.
docs/javascript/webpack.md
Two webpack guides in different categories. What's the difference?
4. Style Inconsistencies:
Some docs are conversational:
From getting-started.md:3:
> **š” Looking for the fastest way to get started?** Try our **[15-Minute Quick Start Guide](./quick-start/README.md)** instead.
Some are formal reference: From API docs:
## react_component_hash for Render-Functions
Another reason to use a Render-Function is that sometimes in server rendering, specifically with React Router, you need to return the result of calling ReactDOMServer.renderToString(element).
Some use checkboxes:
From getting-started.md:30-34:
ā
**šØ React on Rails 16.0+** (this guide covers modern features)
ā
**šØ Shakapacker 6+** (7+ recommended for React on Rails 16)
ā
**Rails 7+** (Rails 5.2+ supported)
Some use tables:
From README.md:42-49:
| I want to... | Go here |
| ----------------------------------- | ------------------------------------------------------------------------- |
| **Add React to existing Rails app** | [Installation Guide](./guides/installation-into-an-existing-rails-app.md) |
Impact:
Better Pattern:
Clear document types with defined purposes:
Each type has:
Problem: Documentation uses relative links that may break during site reorganization.
Examples of Relative Link Patterns:
From getting-started.md:
See file [docs/basics/configuration.md](./guides/configuration.md)
From README.md:
- **[Quick Start](./quick-start/README.md)**
- **[Tutorial](./guides/tutorial.md)**
- **[Installation Guide](./guides/installation-into-an-existing-rails-app.md)**
Risks:
gatsby-node.js) transforms these paths:// From: ./guides/tutorial.md
// To: /react-on-rails/docs/guides/tutorial/
Evidence of Potential Issues:
From docs/planning/DOCUMENTATION_IMPROVEMENT_PLAN.md exists but may have broken links to docs that were moved.
Problem: Image references and asset management unclear.
From getting-started.md:168:
Questions:
docs/images/ folder exists)Problem: No clear search functionality or metadata for discovery.
Observations:
---
title: Getting Started
description: Install React on Rails
keywords: [installation, setup, rails]
---
Impact:
Critical Missing Page: Introduction explaining the value proposition.
What's Missing:
Problem statement:
Comparison with alternatives:
When to use / when not to use:
Architecture overview:
Current Situation:
docs/guides/react-on-rails-overview.md exists but not clearly positioned as THE introduction.
Impact:
Problem: Sparse guidance on migrating existing applications.
What Exists:
docs/additional-details/migrating-from-react-rails.md - Only one migration guidedocs/guides/upgrading-react-on-rails.md - Version upgradesWhat's Missing:
Migrating from plain Rails views:
Migrating from separate React frontend:
Migrating from Hotwire/Turbo:
Version-to-version migration:
Impact:
Problem: Troubleshooting docs are scattered without clear starting point.
Current Troubleshooting Docs:
docs/troubleshooting/README.mddocs/javascript/troubleshooting-build-errors.mddocs/javascript/troubleshooting-when-using-shakapacker.mddocs/javascript/troubleshooting-when-using-webpacker.mdWhat's Missing:
Diagnostic flow:
Issue ā Is it build-time or run-time?
ā Client or server?
ā Webpack or Rails?
ā [Specific guide]
Common error messages:
Debugging tools:
Getting help:
Impact:
Next.js Strengths We're Missing:
Clear learning path:
Interactive examples:
Version switcher:
Rich media:
Source: https://nextjs.org/docs
TanStack Strengths We're Missing:
Clear difficulty levels:
Framework adapters clearly separated:
Examples repository:
API documentation generated from code:
Source: https://tanstack.com/router/latest/docs/framework/react/overview
Rails Guides Strengths We're Missing:
Consistent structure:
Glossary:
Contributing guide prominent:
Edge guides separate:
Source: https://guides.rubyonrails.org
Highest Impact Problems:
Secondary Problems:
Technical Debt:
This analysis will inform:
Priority Order: