internal/planning/docs-improvement/ia-redesign-live.md
Purpose: Track actual implementation progress for the documentation IA redesign. This file tracks what we're actually doing and may diverge from the original plan as we learn and adapt.
Reference Plan: See 04-ia-redesign-plan.md for the detailed original plan.
Branch: feature/docs-ia-redesign
Started: October 2, 2025
We're breaking Phase 2 (File Reorganization) into 8 reviewable steps, pausing between each for review before proceeding.
feature/docs-ia-redesignStatus: In Progress Started: October 2, 2025
git mvRationale: Small, clear category to validate our approach.
Status: Pending Files to move: TBD (from plan mapping)
git mvStatus: Pending
git mvStatus: Pending
git mvStatus: Pending
git mvStatus: Pending
git mvStatus: Pending
git mvStatus: Pending
introduction.md homepagehome.md and README.mdStatus: Pending
This section tracks any deviations from the original plan and why we made them.
Original plan: Category 6 called "Migration & Upgrading" in one folder migration/
Decision: Split into TWO separate categories:
upgrading/) - Version upgrades, release notesmigrating/) - From other tools (react-rails, angular, etc.)Rationale:
New category structure:
1. 🚀 Getting Started
2. 📚 Core Concepts
3. 🔧 Building Features
4. 📖 API Reference
5. 🚢 Deployment
6. 📈 Upgrading ← NEW (split from Migration & Upgrading)
7. 🔄 Migrating ← NEW (split from Migration & Upgrading)
8. 💎 Pro
Files affected:
upgrading/: upgrading-react-on-rails.md, release notes, version-specific guidesmigrating/: from-react-rails.md, from-angular.mdQuestion: Should we rename installation-into-an-existing-rails-app.md to just installation.md?
Decision: Keep the original long descriptive filename.
Rationale:
tutorial.md covers installation for NEW apps (with rails new)installation-into-an-existing-rails-app.md covers EXISTING apps (already have code)installation.md creates ambiguity - users won't know which scenario it coversPattern: Prefer descriptive filenames over short ones when there's meaningful distinction.
Question: Should configuration.md go in Core Concepts or API Reference?
Decision: Move to API Reference.
Rationale:
configuration.md is a 391-line reference list of ALL config optionsview-helpers-api.md and javascript-api.md (method/parameter lists)Pattern: Reference lists of options/methods/parameters belong in API Reference, not Core Concepts.
Context: After completing Step 5 (moving Deployment files), we reviewed what actually ended up in deployment/ and found several files that don't belong.
Problem: The plan placed these files in Deployment, but upon review they're not deployment-specific.
Decision: Move these 5 files OUT of Deployment to proper categories (keeping original filenames per Decision 2):
updating-dependencies.md → misc/updating-dependencies.md (temporary holding)turbolinks.md → building-features/turbolinks.md (feature integration)rails-engine-integration.md → advanced-topics/rails-engine-integration.md (temporary holding)convert-rails-5-api-only-app.md → migrating/convert-rails-5-api-only-app.md (prerequisite migration)rails_view_rendering_from_inline_javascript.md → api-reference/rails_view_rendering_from_inline_javascript.md (API reference)New temporary categories created:
misc/ - For files that don't fit elsewhere (review at end)advanced-topics/ - For advanced setup scenarios (review at end)Deployment category now contains (7 files):
Rationale:
Pattern: Categorize by WHEN and WHY users need the info, not by what technology it involves.
Question: Should we create a "Rails" category for Rails-specific files?
Decision: NO - do not create a "Rails" category.
Rationale:
rails/ folder distributed to appropriate categories by intentPattern: Intent-based categorization (user journey) beats technology-based categorization.
Problem: Three files overlap significantly in covering installation:
rails new)rails newIssue: Users may be confused about which guide to follow. Content is redundant.
Status: Flagged for Section 2 (Content Improvements) - NOT fixing during IA reorg
Next steps: After completing IA restructuring, evaluate whether to:
This is a content problem, not a structure problem. Keep moving files for now.
gatsby develop in sc-website repo pointing to this branchTest results will be logged here as we go
✅ ALL STEPS COMPLETE (Steps 1-8):
✅ ORPHANED FILES REORGANIZED (12 files): After Steps 1-8, found 12 files not in original plan. Investigated and reorganized:
Total files moved: ~50+ files across all steps
Branch: feature/docs-ia-redesign-1845-continue (continuing from merged PR #1845)
✅ Deleted orphaned docs/guides/advanced/README.md
✅ Created docs/introduction.md - New unified homepage
✅ Deleted docs/core-concepts/react-on-rails-overview.md
✅ Simplified docs/README.md for GitHub users
✅ Deleted docs/home.md
✅ Transformed docs/getting-started.md → docs/getting-started/using-react-on-rails.md
✅ Deleted docs/advanced-topics/manual-installation-overview.md
/client, webpacker, missing auto-bundlingdocs/getting-started.mdRemaining Entry Point Tasks:
Next Actions: Update website config when ready (keeping for last as user requested)
docs/
├── introduction.md # ✅ Created - new unified homepage
├── README.md # ✅ Simplified for GitHub users
├── getting-started/ (5 files)
│ ├── using-react-on-rails.md # ✅ NEW - Transformed from getting-started.md
│ ├── quick-start.md
│ ├── installation-into-an-existing-rails-app.md
│ ├── tutorial.md
│ └── project-structure.md
├── core-concepts/ (7 files)
│ ├── how-react-on-rails-works.md
│ ├── client-vs-server-rendering.md
│ ├── react-server-rendering.md
│ ├── render-functions-and-railscontext.md
│ ├── render-functions.md # Orphaned: detailed render-functions guide
│ ├── auto-bundling-file-system-based-automated-bundle-generation.md
│ └── webpack-configuration.md
├── building-features/ (15 files)
│ ├── hmr-and-hot-reloading-with-the-webpack-dev-server.md
│ ├── i18n.md
│ ├── rspec-configuration.md
│ ├── minitest-configuration.md
│ ├── streaming-server-rendering.md
│ ├── how-to-conditionally-server-render-based-on-device-type.md
│ ├── how-to-use-different-files-for-client-and-server-rendering.md
│ ├── react-router.md
│ ├── react-and-redux.md
│ ├── react-helmet.md
│ ├── rails-webpacker-react-integration-options.md
│ ├── code-splitting.md # Moved to outdated/ (marked outdated)
│ ├── images.md
│ ├── foreman-issues.md
│ └── turbolinks.md # Step 5 correction: from deployment
├── api-reference/ (7 files)
│ ├── README.md # Orphaned: index page
│ ├── view-helpers-api.md
│ ├── javascript-api.md
│ ├── redux-store-api.md
│ ├── configuration.md
│ ├── generator-details.md
│ └── rails_view_rendering_from_inline_javascript.md # Step 5 correction: from rails/
├── deployment/ (10 files)
│ ├── deployment.md
│ ├── capistrano-deployment.md
│ ├── heroku-deployment.md
│ ├── elastic-beanstalk.md
│ ├── troubleshooting-build-errors.md
│ ├── troubleshooting-when-using-shakapacker.md
│ ├── troubleshooting-when-using-webpacker.md
│ ├── server-rendering-tips.md # Orphaned: SSR debugging
│ ├── troubleshooting.md # Orphaned: comprehensive troubleshooting
│ └── (removed 4 files in Step 5 corrections)
├── upgrading/ (3 files)
│ ├── upgrading-react-on-rails.md
│ └── release-notes/
│ ├── 15.0.0.md
│ └── 16.0.0.md
├── migrating/ (3 files)
│ ├── migrating-from-react-rails.md
│ ├── angular-js-integration-migration.md
│ └── convert-rails-5-api-only-app.md # Step 5 correction: from deployment
├── pro/ (2 files)
│ ├── react-on-rails-pro.md
│ └── major-performance-breakthroughs-upgrade-guide.md
├── misc/ (7 files - KEEPING as category)
│ ├── updating-dependencies.md # Step 5 correction + merged node-deps
│ ├── credits.md # Orphaned: acknowledgments
│ ├── asset-pipeline.md # Orphaned: warning guide
│ ├── articles.md
│ ├── code_of_conduct.md
│ ├── doctrine.md
│ ├── style.md
│ └── tips.md
└── advanced-topics/ (1 file - KEEPING as category)
└── rails-engine-integration.md # Step 5 correction: from deployment
Final Decisions:
misc/ and advanced-topics/ are now PERMANENT categories (not temporary)See 04-ia-redesign-plan.md for original plan (NOTE: this live doc is source of truth after Steps 1-8 + orphaned files).