internal/planning/docs-improvement/04-ia-redesign-plan.md
Date: September 30, 2025
Scope: Addresses Problems 1.1, 1.2, 1.3, 1.4 from 01-problem-analysis.md
Goal: Create clear, logical navigation that guides users from beginner to advanced
This plan tackles ALL four Information Architecture problems identified in Section 1:
Core Strategy: Redesign from user needs, not implementation details. Group by user journey stage (getting started ā learning ā building ā troubleshooting ā reference).
11 Categories with No Clear Logic:
1. [Root] ā Misc files at root
2. Guides ā 21 files, everything from installation to advanced SSR
3. Rails ā 5 files, Rails-specific topics
4. Javascript ā 17 files, webpack/bundling/tools
5. Additional details ā 7 files, catch-all
6. Deployment ā 2 files, production setup
7. React on rails pro ā 2 files, Pro features
8. Api ā 3 files, reference docs
9. Misc ā 5 files, another catch-all
10. Contributor info ā 6 files, internal docs (WRONG AUDIENCE)
11. Testimonials ā 3 files, marketing (WRONG CONTEXT)
12. Outdated ā 5 files, deprecated (WRONG TO SHOW)
Total: 93 markdown files across these categories.
User Pain Points:
How do we know this redesign worked?
Navigation clarity:
Content organization:
Professional appearance:
User feedback:
Based on user journey stages:
1. š Getting Started [Onboarding, first component]
2. š Core Concepts [SSR, bundling, how it works]
3. š§ Building Features [Common patterns, real-world examples]
4. š API Reference [View helpers, config, JS API]
5. š¢ Deployment [Production, performance, troubleshooting]
6. š Upgrading [Version upgrades, release notes]
7. š Migrating [From other tools: react-rails, angular]
8. š React on Rails Pro [Pro features]
Removed from user navigation:
/contributing/ or CONTRIBUTING.mdPurpose: Get users from zero to first working component ASAP.
Contents:
Introduction (NEW - see Section 1.2 solution)
Quick Start (quick-start/README.md)
Installation (guides/installation-into-an-existing-rails-app.md)
Tutorial (guides/tutorial.md)
Project Structure (additional-details/recommended-project-structure.md)
Current location ā New location:
docs/quick-start/README.md ā getting-started/quick-start.md
docs/guides/installation-into-an-existing-rails-app.md ā getting-started/installation-into-an-existing-rails-app.md
docs/guides/tutorial.md ā getting-started/tutorial.md
docs/additional-details/recommended-project-structure.md ā getting-started/project-structure.md
NEW: docs/introduction.md ā docs/introduction.md (HOMEPAGE)
Purpose: Explain fundamental concepts users need to understand.
Contents:
guides/how-react-on-rails-works.md)guides/react-on-rails-overview.md)guides/client-vs-server-rendering.md)guides/react-server-rendering.md)guides/render-functions-and-railscontext.md)guides/auto-bundling-file-system-based-automated-bundle-generation.md)guides/webpack-configuration.md)NEW docs needed (from Problem 2.1):
Current location ā New location:
docs/guides/how-react-on-rails-works.md ā core-concepts/how-it-works.md
docs/guides/react-on-rails-overview.md ā core-concepts/overview.md
docs/guides/client-vs-server-rendering.md ā core-concepts/client-vs-server-rendering.md
docs/guides/react-server-rendering.md ā core-concepts/server-rendering.md
docs/guides/render-functions-and-railscontext.md ā core-concepts/render-functions-and-railscontext.md
docs/guides/auto-bundling-file-system-based-automated-bundle-generation.md ā core-concepts/auto-bundling.md
docs/guides/webpack-configuration.md ā core-concepts/webpack-configuration.md
Purpose: Practical guides for building real features.
Contents:
Common Patterns:
guides/hmr-and-hot-reloading-with-the-webpack-dev-server.md)guides/i18n.md)guides/rspec-configuration.md)guides/minitest-configuration.md)Advanced Techniques:
guides/streaming-server-rendering.md) - ADVANCEDguides/how-to-conditionally-server-render-based-on-device-type.md)guides/how-to-use-different-files-for-client-and-server-rendering.md)Integration Guides:
javascript/react-router.md)javascript/react-and-redux.md)javascript/react-helmet.md)guides/rails-webpacker-react-integration-options.md)Tools & Workflow:
javascript/code-splitting.md)javascript/images.md)javascript/foreman-issues.md)Current location ā New location:
docs/guides/hmr-and-hot-reloading-with-the-webpack-dev-server.md ā Building/HMR
docs/guides/i18n.md ā Building/Internationalization
docs/guides/rspec-configuration.md ā Building/Testing (RSpec)
docs/guides/minitest-configuration.md ā Building/Testing (Minitest)
docs/guides/streaming-server-rendering.md ā Building/Advanced SSR
docs/guides/how-to-conditionally-server-render-based-on-device-type.md ā Building/Conditional Rendering
docs/guides/how-to-use-different-files-for-client-and-server-rendering.md ā Building/Client/Server Files
docs/javascript/react-router.md ā Building/React Router
docs/javascript/react-and-redux.md ā Building/Redux
docs/javascript/react-helmet.md ā Building/React Helmet
docs/javascript/code-splitting.md ā Building/Code Splitting
docs/javascript/images.md ā Building/Images
Purpose: Quick lookup for syntax, options, parameters.
Contents:
View Helpers (api/view-helpers-api.md)
JavaScript API (api/javascript-api.md)
Redux Store API (api/redux-store-api.md)
Configuration API (guides/configuration.md)
Generator Options (additional-details/generator-details.md)
Current location ā New location:
docs/api/view-helpers-api.md ā api-reference/view-helpers-api.md
docs/api/javascript-api.md ā api-reference/javascript-api.md
docs/api/redux-store-api.md ā api-reference/redux-store-api.md
docs/guides/configuration.md ā api-reference/configuration.md
docs/additional-details/generator-details.md ā api-reference/generator-details.md
Purpose: Production deployment, troubleshooting, performance.
Contents:
Production Setup:
guides/deployment.md)deployment/heroku-deployment.md)deployment/elastic-beanstalk.md)javascript/capistrano-deployment.md)Troubleshooting:
troubleshooting/README.md) - ā
Already good from PR #1813javascript/troubleshooting-build-errors.md)javascript/troubleshooting-when-using-shakapacker.md)javascript/troubleshooting-when-using-webpacker.md)Maintenance:
additional-details/updating-dependencies.md)misc/tips.md - rename/move)Rails-Specific:
rails/turbolinks.md)rails/rails-engine-integration.md)rails/convert-rails-5-api-only-app.md)Current location ā New location:
docs/guides/deployment.md ā Deployment/Production Setup
docs/deployment/heroku-deployment.md ā Deployment/Heroku
docs/deployment/elastic-beanstalk.md ā Deployment/AWS
docs/troubleshooting/README.md ā Deployment/Troubleshooting
docs/javascript/troubleshooting-build-errors.md ā Deployment/Build Errors
docs/additional-details/updating-dependencies.md ā Deployment/Maintenance
docs/rails/turbolinks.md ā Deployment/Turbolinks
docs/rails/rails-engine-integration.md ā Deployment/Rails Engines
Purpose: Help users upgrade between React on Rails versions.
Contents:
guides/upgrading-react-on-rails.md)release-notes/ folder)release-notes/16.0.0.md)release-notes/15.0.0.md)react-on-rails-pro/major-performance-breakthroughs-upgrade-guide.md)Current location ā New location:
docs/guides/upgrading-react-on-rails.md ā upgrading/upgrading-react-on-rails.md
docs/react-on-rails-pro/major-performance-breakthroughs-upgrade-guide.md ā upgrading/pro-performance-upgrade.md
docs/release-notes/ ā upgrading/release-notes/
Purpose: Help users migrate TO React on Rails from other tools.
Contents:
additional-details/migrating-from-react-rails.md)javascript/angular-js-integration-migration.md)Could add (if valuable):
Current location ā New location:
docs/additional-details/migrating-from-react-rails.md ā migrating/from-react-rails.md
docs/javascript/angular-js-integration-migration.md ā migrating/from-angular.md
Purpose: Showcase Pro features, link to Pro docs.
Contents:
react-on-rails-pro/react-on-rails-pro.md)react-on-rails-pro/major-performance-breakthroughs-upgrade-guide.md)Current location ā New location:
docs/react-on-rails-pro/react-on-rails-pro.md ā pro/react-on-rails-pro.md
docs/react-on-rails-pro/major-performance-breakthroughs-upgrade-guide.md ā pro/major-performance-breakthroughs-upgrade-guide.md
Contributor Info ā Not in User Docs
docs/contributor-info/linters.md ā CONTRIBUTING.md or separate /contributing site
docs/contributor-info/coding-agents-guide.md ā CONTRIBUTING.md
docs/contributor-info/errors-with-hooks.md ā CONTRIBUTING.md
docs/contributor-info/generator-testing.md ā CONTRIBUTING.md
docs/contributor-info/releasing.md ā CONTRIBUTING.md
docs/contributor-info/pull-requests.md ā CONTRIBUTING.md
Testimonials ā Marketing Website
docs/testimonials/testimonials.md ā shakacode.com/testimonials
docs/testimonials/hvmn.md ā shakacode.com/case-studies/hvmn
docs/testimonials/resortpass.md ā shakacode.com/case-studies/resortpass
Outdated ā Hidden (Keep in Repo)
docs/outdated/* ā Excluded from build, kept for historical reference
Planning/Internal ā Excluded from Build
docs/planning/* ā Excluded via gatsby-node.js filter
docs/MONOREPO_MERGER_PLAN.md ā Excluded via gatsby-node.js filter
docs/DIRECTORY_LICENSING.md ā Excluded via gatsby-node.js filter
docs/LICENSING_FAQ.md ā Maybe move to root? Or exclude?
Misc Category ā Dissolved
docs/misc/tips.md ā Deployment/Performance Tips
docs/misc/doctrine.md ā Introduction (philosophy section)
docs/misc/articles.md ā External Resources (in introduction or footer)
docs/misc/style.md ā CONTRIBUTING.md
docs/misc/code_of_conduct.md ā Root CODE_OF_CONDUCT.md
Javascript Category ā Dissolved Integrated into Building Features and Deployment categories (see above)
Rails Category ā Dissolved Integrated into Deployment category (see above)
Additional Details Category ā Dissolved Integrated into various categories (see above)
Problem: Users land on different pages with no clear "start here":
docs/README.md (173 lines) - Navigation hubdocs/home.md (29 lines) - Minimal landingdocs/getting-started.md (254 lines) - Installation + concepts + reference (too much)docs/quick-start/README.md (212 lines) - 15-minute pathREADME.md - Project README (not docs landing page)Create ONE landing page: docs/introduction.md
This becomes the homepage when users visit /react-on-rails/docs/
Structure:
# React on Rails
> Integrate React seamlessly into your Rails application with server-side rendering, hot reloading, and more.
## What is React on Rails?
[2-3 paragraphs explaining what it is, what problems it solves]
## Why React on Rails?
[Comparison with alternatives: plain Rails, separate SPA, Hotwire, Inertia.js]
[When to use React on Rails vs. alternatives]
## Quick Decision Guide
**Choose React on Rails if:**
- ā
You have an existing Rails app
- ā
You want React's component model
- ā
You need server-side rendering for SEO/performance
- ā
You want to leverage Rails conventions
**Consider alternatives if:**
- ā You're building a separate API + SPA
- ā You want minimal JavaScript (try Hotwire)
- ā You need cutting-edge React features only (React Server Components in standalone Next.js)
## Getting Started
Choose your path:
### š New to React on Rails?
**[15-Minute Quick Start ā](./quick-start/README.md)**
Get your first component running in minutes.
### š¦ Adding to Existing Rails App?
**[Installation Guide ā](./getting-started/installation.md)**
Detailed integration instructions.
### š Want Comprehensive Tutorial?
**[Complete Tutorial ā](./getting-started/tutorial.md)**
Step-by-step with Redux, routing, and testing.
## Core Concepts
Before diving deep, understand these fundamentals:
- [How React on Rails Works](./core-concepts/how-it-works.md)
- [Client vs. Server Rendering](./core-concepts/rendering.md)
- [Component Registration](./core-concepts/components.md)
- [Webpack Integration](./core-concepts/webpack.md)
## Popular Use Cases
[Table linking to specific guides for common scenarios]
## Philosophy & Principles
[Extract from docs/misc/doctrine.md]
React on Rails values transparency over magic, flexibility over convention...
## Community & Support
- GitHub Discussions
- Slack
- Professional Support
## External Resources
[Link to articles, videos, case studies on marketing site]
What happens to other files:
docs/home.md ā DELETE (redundant)docs/README.md ā DELETE or simplify to just TOC (not landing page)docs/getting-started.md ā SPLIT:
docs/getting-started/installation.mddocs/quick-start/README.md ā KEEP (but clearly positioned as one of three paths)README.md ā KEEP (project README, not docs entry)Result:
introduction.mdFile: /home/ihab/ihab/work/shakacode/sc-website/gatsby-node.js
Changes needed:
1. Update category order (lines 31-44):
// OLD:
const reactOnRailsDocsFoldersOrder = [
firstCategory,
'Guides',
'Rails',
'Javascript',
'Additional details',
'Deployment',
'React on rails pro',
'Api',
'Misc',
'Contributor info',
'Testimonials',
'Outdated',
];
// NEW:
const reactOnRailsDocsFoldersOrder = [
firstCategory, // For introduction.md at root
'Getting Started',
'Core Concepts',
'Building Features',
'API Reference',
'Deployment',
'Migration & Upgrading',
'React on Rails Pro',
];
2. Add filter to exclude internal docs (around line 151):
// OLD:
docs: allFile(
filter: {
dir: { regex: "/^.*/gatsby-source-git/.*$/" }
extension: { in: ["md", "mdx"] }
}
)
// NEW:
docs: allFile(
filter: {
dir: { regex: "/^.*/gatsby-source-git/.*$/" }
extension: { in: ["md", "mdx"] }
# Exclude internal docs
relativePath: {
nin: [
"/contributor-info/",
"/testimonials/",
"/outdated/",
"/planning/",
"/MONOREPO_MERGER_PLAN.md",
"/MONOREPO_MERGER_PLAN_REF.md",
"/DIRECTORY_LICENSING.md",
]
}
}
)
Note: Syntax needs to be checked - GraphQL filter syntax in Gatsby. May need different approach:
nin (not in) operator3. Update index page handling (around line 196):
// Ensure introduction.md becomes homepage
const indexPages = ['introduction'];
Testing checklist:
gatsby develop locally in sc-websiteStrategy: Move files to match new category structure
Approach options:
Option A: Create new folders matching categories
docs/
āāā introduction.md # NEW HOMEPAGE
āāā getting-started/
ā āāā quick-start.md
ā āāā installation.md
ā āāā tutorial.md
ā āāā project-structure.md
āāā core-concepts/
ā āāā how-it-works.md
ā āāā overview.md
ā āāā rendering.md
ā āāā ...
āāā building/
ā āāā hmr.md
ā āāā i18n.md
ā āāā ...
āāā api-reference/
āāā deployment/
āāā migration/
āāā pro/
Option B: Keep current folders, rely on categories
Recommendation: Option A (new folders)
git mvFile moves needed:
Create script: scripts/reorganize-docs.sh
#!/bin/bash
# Reorganize docs to match new IA
# Create new directories
mkdir -p docs/getting-started
mkdir -p docs/core-concepts
mkdir -p docs/building
mkdir -p docs/api-reference
mkdir -p docs/deployment
mkdir -p docs/migration
mkdir -p docs/pro
# Move files (using git mv to preserve history)
# Getting Started
git mv docs/quick-start/README.md docs/getting-started/quick-start.md
git mv docs/guides/installation-into-an-existing-rails-app.md docs/getting-started/installation.md
git mv docs/guides/tutorial.md docs/getting-started/tutorial.md
git mv docs/additional-details/recommended-project-structure.md docs/getting-started/project-structure.md
# Core Concepts
git mv docs/guides/how-react-on-rails-works.md docs/core-concepts/how-it-works.md
git mv docs/guides/react-on-rails-overview.md docs/core-concepts/overview.md
git mv docs/guides/client-vs-server-rendering.md docs/core-concepts/rendering.md
git mv docs/guides/react-server-rendering.md docs/core-concepts/server-rendering.md
git mv docs/guides/render-functions-and-railscontext.md docs/core-concepts/components.md
git mv docs/guides/auto-bundling-file-system-based-automated-bundle-generation.md docs/core-concepts/auto-bundling.md
git mv docs/guides/webpack-configuration.md docs/core-concepts/webpack.md
git mv docs/guides/configuration.md docs/core-concepts/configuration.md
# Building Features
git mv docs/guides/hmr-and-hot-reloading-with-the-webpack-dev-server.md docs/building/hmr.md
git mv docs/guides/i18n.md docs/building/i18n.md
git mv docs/guides/rspec-configuration.md docs/building/testing-rspec.md
git mv docs/guides/minitest-configuration.md docs/building/testing-minitest.md
git mv docs/guides/streaming-server-rendering.md docs/building/streaming-ssr.md
git mv docs/guides/how-to-conditionally-server-render-based-on-device-type.md docs/building/conditional-rendering.md
git mv docs/javascript/react-router.md docs/building/react-router.md
git mv docs/javascript/react-and-redux.md docs/building/redux.md
# API Reference
git mv docs/api docs/api-reference
# Deployment
git mv docs/guides/deployment.md docs/deployment/production.md
git mv docs/troubleshooting/README.md docs/deployment/troubleshooting.md
# ... etc
# Migration
git mv docs/guides/upgrading-react-on-rails.md docs/migration/upgrading.md
git mv docs/additional-details/migrating-from-react-rails.md docs/migration/from-react-rails.md
# Pro
git mv docs/react-on-rails-pro docs/pro
# Remove old empty directories
rmdir docs/guides
rmdir docs/javascript
rmdir docs/rails
rmdir docs/additional-details
rmdir docs/misc
rmdir docs/quick-start
echo "ā
Files reorganized. Review changes before committing."
Testing checklist:
STATUS: ā COMPLETED (with adaptations) - See ia-redesign-live.md for details
Create new files:
1. docs/introduction.md ā
DONE
2. Split docs/getting-started.md: ā
DONE (but transformed, not split)
docs/getting-started/installation.mddocs/getting-started/using-react-on-rails.md (conceptual guide)3. Update docs/README.md: ā
DONE (kept simplified)
4. Delete docs/home.md: ā
DONE
ADDITIONS (discovered during implementation):
5. Tutorial improvements ā DONE
6. Delete manual-installation-overview.md ā
DONE
7. Update cross-references: ā DONE (manually)
Testing checklist:
Move contributor content:
Update CONTRIBUTING.md to include:
docs/contributor-info/linters.mddocs/contributor-info/coding-agents-guide.mddocs/contributor-info/generator-testing.mddocs/contributor-info/releasing.mddocs/contributor-info/pull-requests.mddocs/misc/style.mdOR create /contributing/ documentation site (separate from user docs)
Delete after moving:
rm -rf docs/contributor-info
rm docs/misc/style.md
Move to root:
git mv docs/misc/code_of_conduct.md CODE_OF_CONDUCT.md
Testing checklist:
In react_on_rails repo:
# Remove testimonials from docs
rm -rf docs/testimonials
In sc-website repo:
/testimonials/ or /case-studies/ pageTesting checklist:
Options:
Option A: Hide from build, keep in repo
# Keep files but exclude from gatsby build
# Already done in Phase 1 (gatsby-node.js filter)
Option B: Move to separate branch
git checkout -b archive/outdated-docs
git mv docs/outdated /
git commit -m "Archive outdated docs"
git checkout main
rm -rf docs/outdated
Option C: Delete entirely
rm -rf docs/outdated
Recommendation: Option A (keep in repo, exclude from build)
Testing checklist:
sc-website repo:gatsby-node.js
reactOnRailsDocsFoldersOrder (lines 31-44)Test locally:
react_on_rails repo:New files:
docs/introduction.md (homepage)scripts/reorganize-docs.sh (file moving script)scripts/update-links.sh (link updating script)Modified files:
CONTRIBUTING.md (add contributor content)Deleted files:
docs/home.mddocs/README.md (or drastically simplified)docs/getting-started.md (content extracted)docs/contributor-info/* (moved to CONTRIBUTING.md)docs/testimonials/* (moved to marketing site)docs/misc/style.md (moved to CONTRIBUTING.md)Moved files:
Conservative estimate with testing:
| Phase | Tasks | Estimated Time |
|---|---|---|
| Phase 1: Website Config | Update gatsby-node.js, test locally | 2-3 hours |
| Phase 2: File Reorganization | Create script, move files, test | 4-5 hours |
| Phase 3: Content Updates | Create introduction.md, split docs, update links | 6-8 hours |
| Phase 4: Contributor Docs | Move to CONTRIBUTING.md | 2-3 hours |
| Phase 5: Testimonials | Move to marketing site | 2-3 hours |
| Phase 6: Outdated Content | Hide from build | 1 hour |
| Testing & Refinement | End-to-end testing, fix issues | 4-5 hours |
| Documentation | Update README about changes | 1 hour |
| Total | 22-28 hours (~3-4 days) |
Aggressive estimate (if everything goes smoothly): 15-18 hours (~2 days)
If something goes wrong:
In sc-website repo:
git revert <commit-hash>
npm run build
npm run deploy
Result: Old category structure restored immediately.
In react_on_rails repo:
# Revert file moves
git revert <commit-hash-range>
# Or if not committed yet:
git reset --hard HEAD
Result: Files back in original locations.
If only some categories are problematic:
Risk mitigation:
1. Local Gatsby Build (sc-website):
cd sc-website
npm install
gatsby develop
# Visit http://localhost:8000/react-on-rails/docs/
Check:
2. Local React on Rails Testing:
cd react_on_rails
# Check file structure
ls -la docs/
# Run link checker
npm run check-links # if exists, or:
find docs -name "*.md" -exec markdown-link-check {} \;
Check:
3. User Journey Testing:
Test Scenario 1: New User
Test Scenario 2: Experienced User Looking for API
Test Scenario 3: User with Problem
4. Cross-Browser Testing:
1. Production Checks:
# Visit actual site
open https://reactonrails.com/docs/
# Check Google Search Console (after a few days)
# - Are old URLs redirecting?
# - Are new URLs indexed?
2. Monitor Issues:
3. Gather Feedback:
Quantitative:
Qualitative:
1. Justin (Maintainer):
2. Bob (Mentor):
3. Ihab (You):
1. Gatsby Build System:
2. Git History:
git mv to preserve history3. CI/CD Pipeline:
| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| Broken links after move | High | High | Automated link checker, manual testing |
| Category not rendering | Medium | High | Test locally first, staging deploy |
| User confusion during transition | Medium | Medium | Announcement, redirect old URLs |
| Search broken | Low | Medium | Test search on staging |
| Mobile nav issues | Low | High | Cross-device testing |
| Build failures | Low | Critical | Test locally, rollback plan ready |
| Team disagreement on structure | Medium | Low | Get buy-in before starting |
To discuss with team:
Should we keep docs/README.md or delete it?
What to do with docs/misc/doctrine.md?
Should contributor docs be in CONTRIBUTING.md or separate site?
/contributing/ docs site (more discoverable)How to handle testimonials on marketing site?
Should we add version switcher?
Redirect old URLs to new ones?
Before starting implementation:
Review this plan with Justin and Bob
Prioritize phases
Set up staging environment
Create tracking issue
After plan approved:
Start with Phase 1 (website config)
Get feedback early
Move to Phase 2 (file moves)
Complete remaining phases
This plan addresses ALL four Information Architecture problems:
ā 1.1 Unclear Category Hierarchy ā 7 clear categories based on user journey ā 1.2 Multiple Entry Points ā 1 homepage (introduction.md), 3 clear paths ā 1.3 Internal Docs Visible ā Filtered out, moved to CONTRIBUTING.md ā 1.4 Outdated Content Visible ā Hidden from navigation
Expected outcomes:
This is foundational work that makes all future documentation improvements easier. Once the structure is right, we can:
Estimated effort: 22-28 hours (~3-4 days) Risk: Medium (testing and rollback plan mitigate) Impact: š„š„š„ Critical - fixes foundation for all other improvements