diff --git a/docs/README.md b/docs/README.md index 55fd57ac88..94cfad7b30 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,9 +6,9 @@ New to React on Rails? Start here for the fastest path to success: -**β†’ [15-Minute Quick Start Guide](./quick-start/README.md)** +**β†’ [15-Minute Quick Start Guide](./getting-started/quick-start.md)** -Already have Rails + Shakapacker? **β†’ [Add to existing app guide](./guides/installation-into-an-existing-rails-app.md)** +Already have Rails + Shakapacker? **β†’ [Add to existing app guide](./getting-started/installation-into-an-existing-rails-app.md)** ## πŸ“š Learning Paths @@ -18,72 +18,72 @@ Choose your journey based on your experience level: Perfect if you're new to React on Rails -1. **[Quick Start](./quick-start/README.md)** - Get your first component running +1. **[Quick Start](./getting-started/quick-start.md)** - Get your first component running 2. **[Core Concepts](./getting-started.md)** - Understand the basics -3. **[Tutorial](./guides/tutorial.md)** - Build something useful +3. **[Tutorial](./getting-started/tutorial.md)** - Build something useful ### ⚑ **Experienced Developer Path** Jump to what you need -- **[Installation Guide](./guides/installation-into-an-existing-rails-app.md)** - Detailed setup -- **[API Reference](./api/README.md)** - Quick lookup +- **[Installation Guide](./getting-started/installation-into-an-existing-rails-app.md)** - Detailed setup +- **[API Reference](./api-reference/README.md)** - Quick lookup - **[Advanced Features](./guides/advanced/README.md)** - SSR, Redux, Router ### πŸ—οΈ **Migrating from Other Solutions** -- **[From react-rails](./additional-details/migrating-from-react-rails.md)** - Switch from the react-rails gem -- **[Upgrading React on Rails](./guides/upgrading-react-on-rails.md)** - Version upgrade guide +- **[From react-rails](./migrating/migrating-from-react-rails.md)** - Switch from the react-rails gem +- **[Upgrading React on Rails](./upgrading/upgrading-react-on-rails.md)** - Version upgrade guide ## 🎯 Popular Use Cases Find guidance for your specific scenario: -| I want to... | Go here | -| ----------------------------------- | -------------------------------------------------------------------------- | -| **Add React to existing Rails app** | [Installation Guide](./guides/installation-into-an-existing-rails-app.md) | -| **Enable server-side rendering** | [SSR Guide](./guides/react-server-rendering.md) | -| **Set up hot reloading** | [HMR Setup](./guides/hmr-and-hot-reloading-with-the-webpack-dev-server.md) | -| **Use Redux with Rails** | [Redux Integration](./javascript/react-and-redux.md) | -| **Deploy to production** | [Deployment Guide](./guides/deployment.md) | -| **Troubleshoot issues** | [Troubleshooting](./troubleshooting/README.md) | +| I want to... | Go here | +| ----------------------------------- | ------------------------------------------------------------------------------------- | +| **Add React to existing Rails app** | [Installation Guide](./getting-started/installation-into-an-existing-rails-app.md) | +| **Enable server-side rendering** | [SSR Guide](./core-concepts/react-server-rendering.md) | +| **Set up hot reloading** | [HMR Setup](./building-features/hmr-and-hot-reloading-with-the-webpack-dev-server.md) | +| **Use Redux with Rails** | [Redux Integration](./building-features/react-and-redux.md) | +| **Deploy to production** | [Deployment Guide](./deployment/deployment.md) | +| **Troubleshoot issues** | [Troubleshooting](./deployment/troubleshooting.md) | ## πŸ“– Complete Documentation ### Core Guides - **[Getting Started](./getting-started.md)** - Installation and basic setup -- **[Tutorial](./guides/tutorial.md)** - Complete walkthrough with examples -- **[Configuration](./guides/configuration.md)** - All configuration options -- **[View Helpers](./api/view-helpers-api.md)** - Using `react_component` method +- **[Tutorial](./getting-started/tutorial.md)** - Complete walkthrough with examples +- **[Configuration](./api-reference/configuration.md)** - All configuration options +- **[View Helpers](./api-reference/view-helpers-api.md)** - Using `react_component` method ### Features -- **[Server-Side Rendering](./guides/react-server-rendering.md)** - SSR setup and optimization -- **[Auto-Bundling](./guides/auto-bundling-file-system-based-automated-bundle-generation.md)** - Automatic bundle generation -- **[Redux Integration](./javascript/react-and-redux.md)** - State management with Redux -- **[React Router](./javascript/react-router.md)** - Client-side routing -- **[Internationalization](./guides/i18n.md)** - I18n support +- **[Server-Side Rendering](./core-concepts/react-server-rendering.md)** - SSR setup and optimization +- **[Auto-Bundling](./core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md)** - Automatic bundle generation +- **[Redux Integration](./building-features/react-and-redux.md)** - State management with Redux +- **[React Router](./building-features/react-router.md)** - Client-side routing +- **[Internationalization](./building-features/i18n.md)** - I18n support ### Development -- **[Hot Module Replacement](./guides/hmr-and-hot-reloading-with-the-webpack-dev-server.md)** - Fast development workflow -- **[Testing](./guides/rspec-configuration.md)** - Testing React components -- **[Debugging](./javascript/troubleshooting-build-errors.md)** - Common debugging techniques +- **[Hot Module Replacement](./building-features/hmr-and-hot-reloading-with-the-webpack-dev-server.md)** - Fast development workflow +- **[Testing](./building-features/rspec-configuration.md)** - Testing React components +- **[Debugging](./deployment/troubleshooting-build-errors.md)** - Common debugging techniques ### Deployment & Performance -- **[Deployment](./guides/deployment.md)** - Production deployment guide -- **[Performance](./guides/webpack-configuration.md)** - Optimization techniques -- **[Bundle Optimization](./guides/webpack-configuration.md)** - Reduce bundle size +- **[Deployment](./deployment/deployment.md)** - Production deployment guide +- **[Performance](./core-concepts/webpack-configuration.md)** - Optimization techniques +- **[Bundle Optimization](./core-concepts/webpack-configuration.md)** - Reduce bundle size ## πŸ†˜ Need Help? ### Quick Solutions -- **[Troubleshooting Guide](./troubleshooting/README.md)** - Common issues and solutions -- **[FAQ](./troubleshooting/README.md)** - Frequently asked questions -- **[Error Messages](./javascript/troubleshooting-build-errors.md)** - Decode error messages +- **[Troubleshooting Guide](./deployment/troubleshooting.md)** - Common issues and solutions +- **[FAQ](./deployment/troubleshooting.md)** - Frequently asked questions +- **[Error Messages](./deployment/troubleshooting-build-errors.md)** - Decode error messages ### Community Support @@ -108,62 +108,62 @@ Find guidance for your specific scenario: ### API Reference -- [View Helpers API](./api/view-helpers-api.md) -- [Redux Store API](./api/redux-store-api.md) -- [JavaScript API](./api/javascript-api.md) +- [View Helpers API](./api-reference/view-helpers-api.md) +- [Redux Store API](./api-reference/redux-store-api.md) +- [JavaScript API](./api-reference/javascript-api.md) ### Guides #### Getting Started - [Installation](./getting-started.md) -- [Tutorial](./guides/tutorial.md) -- [Basic Configuration](./guides/configuration.md) +- [Tutorial](./getting-started/tutorial.md) +- [Basic Configuration](./api-reference/configuration.md) #### Core Features -- [Server-Side Rendering](./guides/react-server-rendering.md) -- [Component Registration](./guides/render-functions-and-railscontext.md) -- [Props and RailsContext](./guides/render-functions-and-railscontext.md) +- [Server-Side Rendering](./core-concepts/react-server-rendering.md) +- [Component Registration](./core-concepts/render-functions-and-railscontext.md) +- [Props and RailsContext](./core-concepts/render-functions-and-railscontext.md) #### State Management -- [Redux Integration](./javascript/react-and-redux.md) -- [Context API](./guides/render-functions-and-railscontext.md) +- [Redux Integration](./building-features/react-and-redux.md) +- [Context API](./core-concepts/render-functions-and-railscontext.md) #### Routing -- [React Router Setup](./javascript/react-router.md) -- [Server-Side Routing](./guides/react-server-rendering.md) +- [React Router Setup](./building-features/react-router.md) +- [Server-Side Routing](./core-concepts/react-server-rendering.md) #### Advanced Topics -- [Webpack Configuration](./guides/webpack-configuration.md) -- [Code Splitting](./javascript/code-splitting.md) -- [Performance Optimization](./guides/webpack-configuration.md) +- [Webpack Configuration](./core-concepts/webpack-configuration.md) +- [Code Splitting](./building-features/code-splitting.md) +- [Performance Optimization](./core-concepts/webpack-configuration.md) #### Development -- [Hot Module Replacement](./guides/hmr-and-hot-reloading-with-the-webpack-dev-server.md) -- [Testing Components](./guides/rspec-configuration.md) -- [Debugging](./javascript/troubleshooting-build-errors.md) +- [Hot Module Replacement](./building-features/hmr-and-hot-reloading-with-the-webpack-dev-server.md) +- [Testing Components](./building-features/rspec-configuration.md) +- [Debugging](./deployment/troubleshooting-build-errors.md) #### Deployment -- [Production Setup](./guides/deployment.md) -- [Heroku Deployment](./guides/deployment.md) -- [Docker Setup](./guides/deployment.md) +- [Production Setup](./deployment/deployment.md) +- [Heroku Deployment](./deployment/deployment.md) +- [Docker Setup](./deployment/deployment.md) ### Migration Guides -- [Upgrading React on Rails](./guides/upgrading-react-on-rails.md) -- [From react-rails gem](./additional-details/migrating-from-react-rails.md) +- [Upgrading React on Rails](./upgrading/upgrading-react-on-rails.md) +- [From react-rails gem](./migrating/migrating-from-react-rails.md) ### Troubleshooting -- [Common Issues](./troubleshooting/README.md) -- [Error Messages](./javascript/troubleshooting-build-errors.md) -- [Performance Issues](./javascript/troubleshooting-build-errors.md) +- [Common Issues](./deployment/troubleshooting.md) +- [Error Messages](./deployment/troubleshooting-build-errors.md) +- [Performance Issues](./deployment/troubleshooting-build-errors.md) ### Contributing diff --git a/docs/additional-details/updating-dependencies.md b/docs/additional-details/updating-dependencies.md deleted file mode 100644 index 175277fc42..0000000000 --- a/docs/additional-details/updating-dependencies.md +++ /dev/null @@ -1,31 +0,0 @@ -# Updating Dependencies - -If you frequently update dependencies in small batches, you will avoid large and painful updates later. Then again, if you don't have good test coverage, it's hazardous to update dependencies at any time. - -## Ruby - -Delete any unwanted version constraints from your Gemfile and run: - -```bash -bundle update -``` - -## NPM - -1. Install [npm-check-updates](https://www.npmjs.com/package/npm-check-updates) -1. Run `yarn outdated` and read CHANGELOGs of major updated packages before you update. You might not be ready for some updates. -1. Run these commands. You may or may not need to `rm -rf` your `node_modules` directory. - - ```bash - cd client - ncu -u -a - yarn - ``` - -Some combinations that I often run: - -- remove old installed `node_modules` so you only get what corresponds to `package.json`: - - ```bash - ncu -u -a && rm -rf node_modules && yarn - ``` diff --git a/docs/additional-details/manual-installation-overview.md b/docs/advanced-topics/manual-installation-overview.md similarity index 93% rename from docs/additional-details/manual-installation-overview.md rename to docs/advanced-topics/manual-installation-overview.md index 027c4c55b7..6535ce4b91 100644 --- a/docs/additional-details/manual-installation-overview.md +++ b/docs/advanced-topics/manual-installation-overview.md @@ -13,7 +13,7 @@ The only requirements within this directory for basic React on Rails integration 1. Your Webpack configuration files: 1. Create outputs in a directory like `/public/webpack`, which is customizable in your `config/initializers/react_on_rails.rb`. 1. Provide server rendering if you wish to use that feature. -1. Your JavaScript code "registers" any components and stores per the ReactOnRails APIs of ReactOnRails.register(components) and ReactOnRails.registerStore(stores). See [our JavaScript API docs](../api/javascript-api.md) and the [React on Rails source](https://github.com/shakacode/react_on_rails/tree/master/packages/react-on-rails/src/ReactOnRails.client.ts). +1. Your JavaScript code "registers" any components and stores per the ReactOnRails APIs of ReactOnRails.register(components) and ReactOnRails.registerStore(stores). See [our JavaScript API docs](../api-reference/javascript-api.md) and the [React on Rails source](https://github.com/shakacode/react_on_rails/tree/master/packages/react-on-rails/src/ReactOnRails.client.ts). 1. Set your registration file as an "entry" point in your Webpack configs. 1. Configure scripts in `client/package.json` as shown in the example apps. These are used for building your Webpack assets. Also do this for your top-level `package.json`. diff --git a/docs/rails/rails-engine-integration.md b/docs/advanced-topics/rails-engine-integration.md similarity index 100% rename from docs/rails/rails-engine-integration.md rename to docs/advanced-topics/rails-engine-integration.md diff --git a/docs/api-reference/README.md b/docs/api-reference/README.md new file mode 100644 index 0000000000..aa5aa7cc4b --- /dev/null +++ b/docs/api-reference/README.md @@ -0,0 +1,7 @@ +# API Reference + +Complete API documentation for React on Rails. + +- [View Helpers API](../api-reference/view-helpers-api.md) +- [Redux Store API](../api-reference/redux-store-api.md) +- [JavaScript API](../api-reference/javascript-api.md) diff --git a/docs/guides/configuration.md b/docs/api-reference/configuration.md similarity index 100% rename from docs/guides/configuration.md rename to docs/api-reference/configuration.md diff --git a/docs/additional-details/generator-details.md b/docs/api-reference/generator-details.md similarity index 98% rename from docs/additional-details/generator-details.md rename to docs/api-reference/generator-details.md index b31e7908e7..0478cba2d0 100644 --- a/docs/additional-details/generator-details.md +++ b/docs/api-reference/generator-details.md @@ -37,7 +37,7 @@ Then you may run `rails s` ``` -Another good option is to create a simple test app per the [Tutorial](../guides/tutorial.md). +Another good option is to create a simple test app per the [Tutorial](../getting-started/tutorial.md). # Understanding the Organization of the Generated Client Code diff --git a/docs/api/javascript-api.md b/docs/api-reference/javascript-api.md similarity index 100% rename from docs/api/javascript-api.md rename to docs/api-reference/javascript-api.md diff --git a/docs/rails/rails_view_rendering_from_inline_javascript.md b/docs/api-reference/rails_view_rendering_from_inline_javascript.md similarity index 100% rename from docs/rails/rails_view_rendering_from_inline_javascript.md rename to docs/api-reference/rails_view_rendering_from_inline_javascript.md diff --git a/docs/api/redux-store-api.md b/docs/api-reference/redux-store-api.md similarity index 100% rename from docs/api/redux-store-api.md rename to docs/api-reference/redux-store-api.md diff --git a/docs/api/view-helpers-api.md b/docs/api-reference/view-helpers-api.md similarity index 88% rename from docs/api/view-helpers-api.md rename to docs/api-reference/view-helpers-api.md index 7f8cb30480..5204dae36d 100644 --- a/docs/api/view-helpers-api.md +++ b/docs/api-reference/view-helpers-api.md @@ -25,7 +25,7 @@ Uncommonly used options: ``` - **component_name:** Can be a React component, created using a React Function Component, an ES6 class or a Render-Function that returns a React component (or, only on the server side, an object with shape `{ redirectLocation, error, renderedHtml }`), or a "renderer function" that manually renders a React component to the dom (client side only). Note, a "renderer function" is a special type of "Render-Function." A "renderer function" takes a 3rd param of a DOM ID. - All options except `props, id, html_options` will inherit from your `react_on_rails.rb` initializer, as described [here](../guides/configuration.md). + All options except `props, id, html_options` will inherit from your `react_on_rails.rb` initializer, as described [here](../api-reference/configuration.md). - **general options:** - **props:** Ruby Hash which contains the properties to pass to the React object, or a JSON string. If you pass a string, we'll escape it for you. - **prerender:** enable server-side rendering of a component. Set to false when debugging! @@ -105,7 +105,7 @@ You can call `rails_context` or `rails_context(server_side: true|false)` from yo A "renderer function" is a Render-Function that accepts three arguments (rather than 2): `(props, railsContext, domNodeId) => { ... }`. Instead of returning a React component, a renderer is responsible for installing a callback that will call `ReactDOM.render` (in React 16+, `ReactDOM.hydrate`) to render a React component into the DOM. The "renderer function" is called at the same time the document ready event would instantiate the React components into the DOM. -Why would you want to call `ReactDOM.hydrate` yourself? One possible use case is [code splitting](../javascript/code-splitting.md). In a nutshell, you don't want to load the React component on the DOM node yet. So you want to install some handler that will call `ReactDOM.hydrate` at a later time. In the case of code splitting with server rendering, the server rendered code has any async code loaded and used to server render. Thus, the client code must also fully load any asynch code before server rendering. Otherwise, the client code would first render partially, not matching the server rendering, and then a second later, the full code would render, resulting in an unpleasant flashing on the screen. +Why would you want to call `ReactDOM.hydrate` yourself? One possible use case is [code splitting](../building-features/code-splitting.md). In a nutshell, you don't want to load the React component on the DOM node yet. So you want to install some handler that will call `ReactDOM.hydrate` at a later time. In the case of code splitting with server rendering, the server rendered code has any async code loaded and used to server render. Thus, the client code must also fully load any asynch code before server rendering. Otherwise, the client code would first render partially, not matching the server rendering, and then a second later, the full code would render, resulting in an unpleasant flashing on the screen. Renderer functions are not meant to be used on the server since there's no DOM on the server. Instead, use a Render-Function. Attempting to server render with a renderer function will throw an error. @@ -115,9 +115,9 @@ Renderer functions are not meant to be used on the server since there's no DOM o [React Router](https://reactrouter.com/) is supported, including server-side rendering! See: -1. [React on Rails docs for React Router](../javascript/react-router.md) +1. [React on Rails docs for React Router](../building-features/react-router.md) 2. Examples in [spec/dummy/app/views/react_router](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/app/views/react_router) and follow to the JavaScript code in the [spec/dummy/client/app/startup/RouterApp.server.jsx](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/client/app/startup/RouterApp.server.jsx). -3. [Code Splitting docs](../javascript/code-splitting.md) for information about how to set up code splitting for server rendered routes. +3. [Code Splitting docs](../building-features/code-splitting.md) for information about how to set up code splitting for server rendered routes. --- diff --git a/docs/api/README.md b/docs/api/README.md deleted file mode 100644 index a12b0132fc..0000000000 --- a/docs/api/README.md +++ /dev/null @@ -1,7 +0,0 @@ -# API Reference - -Complete API documentation for React on Rails. - -- [View Helpers API](./view-helpers-api.md) -- [Redux Store API](./redux-store-api.md) -- [JavaScript API](./javascript-api.md) diff --git a/docs/javascript/code-splitting.md b/docs/building-features/code-splitting.md similarity index 99% rename from docs/javascript/code-splitting.md rename to docs/building-features/code-splitting.md index 42981ad33b..78b6dc0633 100644 --- a/docs/javascript/code-splitting.md +++ b/docs/building-features/code-splitting.md @@ -71,7 +71,7 @@ ReactOnRails.register({ }); ``` -Note that you should not register a renderer on the server, since there won't be a domNodeId when we're server rendering. Note that the `RouterApp` imported by `serverRegistration.js` is from a different file. For an example of how to set up an app for server rendering, see the [react router docs](./react-router.md). +Note that you should not register a renderer on the server, since there won't be a domNodeId when we're server rendering. Note that the `RouterApp` imported by `serverRegistration.js` is from a different file. For an example of how to set up an app for server rendering, see the [react router docs](../building-features/react-router.md). #### RouterAppRenderer.jsx diff --git a/docs/javascript/foreman-issues.md b/docs/building-features/foreman-issues.md similarity index 100% rename from docs/javascript/foreman-issues.md rename to docs/building-features/foreman-issues.md diff --git a/docs/guides/hmr-and-hot-reloading-with-the-webpack-dev-server.md b/docs/building-features/hmr-and-hot-reloading-with-the-webpack-dev-server.md similarity index 100% rename from docs/guides/hmr-and-hot-reloading-with-the-webpack-dev-server.md rename to docs/building-features/hmr-and-hot-reloading-with-the-webpack-dev-server.md diff --git a/docs/guides/how-to-conditionally-server-render-based-on-device-type.md b/docs/building-features/how-to-conditionally-server-render-based-on-device-type.md similarity index 90% rename from docs/guides/how-to-conditionally-server-render-based-on-device-type.md rename to docs/building-features/how-to-conditionally-server-render-based-on-device-type.md index 747b124112..a376f4047a 100644 --- a/docs/guides/how-to-conditionally-server-render-based-on-device-type.md +++ b/docs/building-features/how-to-conditionally-server-render-based-on-device-type.md @@ -37,4 +37,4 @@ end Note, full details of the React on Rails configuration are [here in docs/basics/configuration.md](https://shakacode.com/react-on-rails/docs/guides/configuration/). -See the doc file [render-functions-and-railscontext.md](./render-functions-and-railscontext.md#rails-context) for how your client-side code uses the device information +See the doc file [render-functions-and-railscontext.md](../core-concepts/render-functions-and-railscontext.md#rails-context) for how your client-side code uses the device information diff --git a/docs/guides/how-to-use-different-files-for-client-and-server-rendering.md b/docs/building-features/how-to-use-different-files-for-client-and-server-rendering.md similarity index 100% rename from docs/guides/how-to-use-different-files-for-client-and-server-rendering.md rename to docs/building-features/how-to-use-different-files-for-client-and-server-rendering.md diff --git a/docs/guides/i18n.md b/docs/building-features/i18n.md similarity index 100% rename from docs/guides/i18n.md rename to docs/building-features/i18n.md diff --git a/docs/javascript/images.md b/docs/building-features/images.md similarity index 100% rename from docs/javascript/images.md rename to docs/building-features/images.md diff --git a/docs/guides/minitest-configuration.md b/docs/building-features/minitest-configuration.md similarity index 100% rename from docs/guides/minitest-configuration.md rename to docs/building-features/minitest-configuration.md diff --git a/docs/guides/rails-webpacker-react-integration-options.md b/docs/building-features/rails-webpacker-react-integration-options.md similarity index 100% rename from docs/guides/rails-webpacker-react-integration-options.md rename to docs/building-features/rails-webpacker-react-integration-options.md diff --git a/docs/javascript/react-and-redux.md b/docs/building-features/react-and-redux.md similarity index 100% rename from docs/javascript/react-and-redux.md rename to docs/building-features/react-and-redux.md diff --git a/docs/javascript/react-helmet.md b/docs/building-features/react-helmet.md similarity index 100% rename from docs/javascript/react-helmet.md rename to docs/building-features/react-helmet.md diff --git a/docs/javascript/react-router.md b/docs/building-features/react-router.md similarity index 85% rename from docs/javascript/react-router.md rename to docs/building-features/react-router.md index 3cae7cbdf1..e908bbe713 100644 --- a/docs/javascript/react-router.md +++ b/docs/building-features/react-router.md @@ -24,14 +24,10 @@ const RouterApp = (props, railsContext) => { }; ``` -For a fleshed out integration of React on Rails with React Router, check out [React Webpack Rails Tutorial Code](https://github.com/shakacode/react-webpack-rails-tutorial), specifically the files: +For a fleshed out integration of React on Rails with React Router, check out [React Webpack Rails Tutorial Code](https://github.com/shakacode/react-webpack-rails-tutorial), specifically the routing configuration in: - [react-webpack-rails-tutorial/client/app/bundles/comments/routes/routes.jsx](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/client/app/bundles/comments/routes/routes.jsx) -- [react-webpack-rails-tutorial/client/app/bundles/comments/startup/ClientRouterApp.jsx](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/client/app/bundles/comments/startup/ClientRouterApp.jsx) - -- [react-webpack-rails-tutorial/client/app/bundles/comments/startup/ServerRouterApp.jsx](https://github.com/shakacode/react-webpack-rails-tutorial/blob/master/client/app/bundles/comments/startup/ServerRouterApp.jsx) - # Server Rendering Using React Router V4 Your Render-Function may not return an object with the property `renderedHtml`. Thus, you call diff --git a/docs/guides/rspec-configuration.md b/docs/building-features/rspec-configuration.md similarity index 97% rename from docs/guides/rspec-configuration.md rename to docs/building-features/rspec-configuration.md index f62b3bcdce..dd5eed763d 100644 --- a/docs/guides/rspec-configuration.md +++ b/docs/building-features/rspec-configuration.md @@ -1,6 +1,6 @@ # RSpec Configuration -_Click [here for minitest](./minitest-configuration.md)_ +_Click [here for minitest](../building-features/minitest-configuration.md)_ # If your Webpack configurations correspond to Shakapacker's default setup @@ -11,7 +11,7 @@ compiled by Webpack before running tests and during production deployment: 1. **Use Shakapacker's compile option**: Configure your `config/shakapacker.yml` so that `compile: true` is for `test` and `production` environments. Ensure that your `source_path` is correct, or else `Shakapacker` won't correctly detect changes. -2. **Use the React on Rails settings and helpers**. Use the settings in `config/initializers/react_on_rails.rb`. Refer to [docs/configuration](./configuration.md). +2. **Use the React on Rails settings and helpers**. Use the settings in `config/initializers/react_on_rails.rb`. Refer to [docs/configuration](../api-reference/configuration.md). ```yml config.build_test_command = "NODE_ENV=test RAILS_ENV=test bin/shakapacker" diff --git a/docs/guides/streaming-server-rendering.md b/docs/building-features/streaming-server-rendering.md similarity index 100% rename from docs/guides/streaming-server-rendering.md rename to docs/building-features/streaming-server-rendering.md diff --git a/docs/rails/turbolinks.md b/docs/building-features/turbolinks.md similarity index 100% rename from docs/rails/turbolinks.md rename to docs/building-features/turbolinks.md diff --git a/docs/guides/auto-bundling-file-system-based-automated-bundle-generation.md b/docs/core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md similarity index 96% rename from docs/guides/auto-bundling-file-system-based-automated-bundle-generation.md rename to docs/core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md index 57a8473f55..8525644ed1 100644 --- a/docs/guides/auto-bundling-file-system-based-automated-bundle-generation.md +++ b/docs/core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md @@ -29,14 +29,14 @@ For example, configure `config/initializers/react_on_rails` to set the name for config.components_subdirectory = "ror_components" ``` -Now all React components inside the directories called `ror_components` will automatically be registered for usage with [`react_component`](../api/view-helpers-api.md#react_component) and [`react_component_hash`](../api/view-helpers-api.md#react_component_hash) helper methods provided by React on Rails. +Now all React components inside the directories called `ror_components` will automatically be registered for usage with [`react_component`](../api-reference/view-helpers-api.md#react_component) and [`react_component_hash`](../api-reference/view-helpers-api.md#react_component_hash) helper methods provided by React on Rails. > Example (dummy app): the configured components subdirectory is named `startup` instead of `ror_components`. > [Dummy initializer](https://github.com/shakacode/react_on_rails/blob/master/spec/dummy/config/initializers/react_on_rails.rb) ### Configure `auto_load_bundle` Option -For automated component registry, [`react_component`](../api/view-helpers-api.md#react_component) and [`react_component_hash`](../api/view-helpers-api.md#react_component_hash) view helper method tries to load generated bundle for component from the generated directory automatically per `auto_load_bundle` option. `auto_load_bundle` option in `config/initializers/react_on_rails` configures the default value that will be passed to component helpers. The default is `false`, and the parameter can be passed explicitly for each call. +For automated component registry, [`react_component`](../api-reference/view-helpers-api.md#react_component) and [`react_component_hash`](../api-reference/view-helpers-api.md#react_component_hash) view helper method tries to load generated bundle for component from the generated directory automatically per `auto_load_bundle` option. `auto_load_bundle` option in `config/initializers/react_on_rails` configures the default value that will be passed to component helpers. The default is `false`, and the parameter can be passed explicitly for each call. You can change the value in `config/initializers/react_on_rails` by updating it as follows: @@ -201,7 +201,7 @@ For example, if you wanted to utilize our file-system based entrypoint generatio <%= react_component("SpecialComponentNotToAutoLoadBundle", {}) %> ``` - If a component uses multiple HTML strings for server rendering, the [`react_component_hash`](../api/view-helpers-api.md#react_component_hash) view helper can be used on the Rails view, as illustrated below. + If a component uses multiple HTML strings for server rendering, the [`react_component_hash`](../api-reference/view-helpers-api.md#react_component_hash) view helper can be used on the Rails view, as illustrated below. ```erb <% foo_component_one_data = react_component_hash( diff --git a/docs/guides/client-vs-server-rendering.md b/docs/core-concepts/client-vs-server-rendering.md similarity index 96% rename from docs/guides/client-vs-server-rendering.md rename to docs/core-concepts/client-vs-server-rendering.md index 4b7e7389f9..1060944b96 100644 --- a/docs/guides/client-vs-server-rendering.md +++ b/docs/core-concepts/client-vs-server-rendering.md @@ -1,6 +1,6 @@ # Client-Side Rendering vs. Server-Side Rendering -_Also, see [our React server-rendering documentation](./react-server-rendering.md)._ +_Also, see [our React server-rendering documentation](../core-concepts/react-server-rendering.md)._ In most cases, you should use the `prerender: false` (default behavior) with the provided helper method to render the React component from your Rails views. In some cases, such as when SEO is vital, or many users will not have JavaScript enabled, you can enable server-rendering by passing `prerender: true` to your helper, or you can simply change the default in `config/initializers/react_on_rails`. diff --git a/docs/guides/how-react-on-rails-works.md b/docs/core-concepts/how-react-on-rails-works.md similarity index 98% rename from docs/guides/how-react-on-rails-works.md rename to docs/core-concepts/how-react-on-rails-works.md index 4cfcaaf7d7..47d7d7e692 100644 --- a/docs/guides/how-react-on-rails-works.md +++ b/docs/core-concepts/how-react-on-rails-works.md @@ -36,7 +36,7 @@ On production deployments that use asset precompilation, such as Heroku deployme However, if you want to run a custom command to run Webpack to build your bundles, then you will: -1. Define `config.build_production_command` in your [config/initializers/react_on_rails.rb](./configuration.md) +1. Define `config.build_production_command` in your [config/initializers/react_on_rails.rb](../api-reference/configuration.md) Then React on Rails modifies the `assets:precompile` task to run your `build_production_command`. diff --git a/docs/guides/react-on-rails-overview.md b/docs/core-concepts/react-on-rails-overview.md similarity index 95% rename from docs/guides/react-on-rails-overview.md rename to docs/core-concepts/react-on-rails-overview.md index ce753b9e41..7abe7ac698 100644 --- a/docs/guides/react-on-rails-overview.md +++ b/docs/core-concepts/react-on-rails-overview.md @@ -16,7 +16,7 @@ To provide a high performance framework for integrating Ruby on Rails with React 1. Support for HMR for a great developer experience. 1. Supports latest versions of React with hooks. 1. [Redux](https://redux.js.org/) and [React Router](https://reactrouter.com/) integration including server-side-rendering. -1. [Internationalization (I18n) and (localization)](./i18n.md) +1. [Internationalization (I18n) and (localization)](../building-features/i18n.md) 1. A supportive community. This [web search shows how live public sites are using React on Rails](https://publicwww.com/websites/%22react-on-rails%22++-undeveloped.com+depth%3Aall/). 1. [ReScript (Reason ML) Support](https://github.com/shakacode/reason-react-on-rails-example). diff --git a/docs/guides/react-server-rendering.md b/docs/core-concepts/react-server-rendering.md similarity index 94% rename from docs/guides/react-server-rendering.md rename to docs/core-concepts/react-server-rendering.md index b7c2420af2..3499751160 100644 --- a/docs/guides/react-server-rendering.md +++ b/docs/core-concepts/react-server-rendering.md @@ -1,6 +1,6 @@ # React Server Rendering -See also [Client vs. Server Rendering](./client-vs-server-rendering.md). +See also [Client vs. Server Rendering](../core-concepts/client-vs-server-rendering.md). ## What is the easiest way to set up a Webpack configuration for server-side-rendering? @@ -14,7 +14,7 @@ During the Rails rendering of HTML per a browser request, the Rails server will The default JavaScript interpreter is [ExecJS](https://github.com/rails/execjs). If you want to maximize the performance of your server rendering, then you want to use React on Rails Pro which uses NodeJS to do the server rendering. See the [docs for React on Rails Pro](https://github.com/shakacode/react_on_rails/wiki). -See [this note](./client-vs-server-rendering.md). +See [this note](../core-concepts/client-vs-server-rendering.md). ## How do you do Server Rendering with React on Rails? diff --git a/docs/guides/render-functions-and-railscontext.md b/docs/core-concepts/render-functions-and-railscontext.md similarity index 97% rename from docs/guides/render-functions-and-railscontext.md rename to docs/core-concepts/render-functions-and-railscontext.md index 58f3d08239..e03513478d 100644 --- a/docs/guides/render-functions-and-railscontext.md +++ b/docs/core-concepts/render-functions-and-railscontext.md @@ -78,7 +78,7 @@ reduxStore = MyReduxStore(props, railsContext); > You never make these calls. React on Rails makes these calls when it does either client or server rendering. You will define functions that take these 2 params and return a React component or a Redux Store. Naturally, you do not have to use second parameter, `railsContext`, if you do not need it. If you don't take a second parameter, then you're probably defining a React function component and you will simply return a React Element, often just JSX. > [!NOTE] -> See [Redux Store](../api/redux-store-api.md#multiple-react-components-on-a-page-with-one-store) on how to set up Redux stores that allow multiple components to talk to the same store. +> See [Redux Store](../api-reference/redux-store-api.md#multiple-react-components-on-a-page-with-one-store) on how to set up Redux stores that allow multiple components to talk to the same store. The `railsContext` has: (see the implementation in [ReactOnRails::Helper](https://github.com/shakacode/react_on_rails/tree/master/lib/react_on_rails/helper.rb), method `rails_context` for the definitive list). diff --git a/docs/javascript/render-functions.md b/docs/core-concepts/render-functions.md similarity index 99% rename from docs/javascript/render-functions.md rename to docs/core-concepts/render-functions.md index f5fba5fa0e..ab7130f9bc 100644 --- a/docs/javascript/render-functions.md +++ b/docs/core-concepts/render-functions.md @@ -7,7 +7,7 @@ This guide explains how render-functions work in React on Rails and how to use t Render-functions take two parameters: 1. `props`: The props passed from the Ruby helper methods (via the `props:` parameter), which become available in your JavaScript. -2. `railsContext`: Rails contextual information like current pathname, locale, etc. See the [Render-Functions and the Rails Context](../guides/render-functions-and-railscontext.md) documentation for more details. +2. `railsContext`: Rails contextual information like current pathname, locale, etc. See the [Render-Functions and the Rails Context](../core-concepts/render-functions-and-railscontext.md) documentation for more details. ### Identifying Render-Functions diff --git a/docs/guides/webpack-configuration.md b/docs/core-concepts/webpack-configuration.md similarity index 93% rename from docs/guides/webpack-configuration.md rename to docs/core-concepts/webpack-configuration.md index cd0ef0e7b7..4a85d5a2d0 100644 --- a/docs/guides/webpack-configuration.md +++ b/docs/core-concepts/webpack-configuration.md @@ -22,7 +22,7 @@ A key decision in your use React on Rails is whether you go with the Shakapacker ## Option 1: Default Generator Setup: Shakapacker app/javascript -Typical Shakapacker apps have a standard directory structure as documented [here](https://github.com/shakacode/shakapacker/blob/master/README.md#configuration-and-code). If you follow [the basic tutorial](./tutorial.md), you will see this pattern in action. In order to customize the Webpack configuration, consult [Webpack Tips](../javascript/webpack.md). +Typical Shakapacker apps have a standard directory structure as documented [here](https://github.com/shakacode/shakapacker/blob/master/README.md#configuration-and-code). If you follow [the basic tutorial](../getting-started/tutorial.md), you will see this pattern in action. In order to customize the Webpack configuration, consult [Webpack Tips](../outdated/webpack.md). The _advantage_ of using Shakapacker to configure Webpack is that there is very little code needed to get started, and you don't need to understand really anything about Webpack customization. @@ -38,5 +38,5 @@ const { config, devServer } = require('shakapacker'); You will want to consider using some of the same values set in these files: -- https://github.com/shakacode/shakapacker/blob/master/package/environments/base.js -- https://github.com/shakacode/shakapacker/blob/master/package/environments/development.js +- https://github.com/shakacode/shakapacker/blob/master/package/environments/base.ts +- https://github.com/shakacode/shakapacker/blob/master/package/environments/development.ts diff --git a/docs/javascript/capistrano-deployment.md b/docs/deployment/capistrano-deployment.md similarity index 100% rename from docs/javascript/capistrano-deployment.md rename to docs/deployment/capistrano-deployment.md diff --git a/docs/guides/deployment.md b/docs/deployment/deployment.md similarity index 100% rename from docs/guides/deployment.md rename to docs/deployment/deployment.md diff --git a/docs/javascript/server-rendering-tips.md b/docs/deployment/server-rendering-tips.md similarity index 100% rename from docs/javascript/server-rendering-tips.md rename to docs/deployment/server-rendering-tips.md diff --git a/docs/javascript/troubleshooting-build-errors.md b/docs/deployment/troubleshooting-build-errors.md similarity index 97% rename from docs/javascript/troubleshooting-build-errors.md rename to docs/deployment/troubleshooting-build-errors.md index 384a7b4653..f35ae6db0d 100644 --- a/docs/javascript/troubleshooting-build-errors.md +++ b/docs/deployment/troubleshooting-build-errors.md @@ -275,6 +275,6 @@ fi ## Need More Help? -- Check the [general troubleshooting guide](./troubleshooting-when-using-shakapacker.md) -- Review [webpack configuration docs](./webpack.md) +- Check the [general troubleshooting guide](../deployment/troubleshooting-when-using-shakapacker.md) +- Review [webpack configuration docs](../outdated/webpack.md) - Contact [justin@shakacode.com](mailto:justin@shakacode.com) for professional support diff --git a/docs/javascript/troubleshooting-when-using-shakapacker.md b/docs/deployment/troubleshooting-when-using-shakapacker.md similarity index 100% rename from docs/javascript/troubleshooting-when-using-shakapacker.md rename to docs/deployment/troubleshooting-when-using-shakapacker.md diff --git a/docs/javascript/troubleshooting-when-using-webpacker.md b/docs/deployment/troubleshooting-when-using-webpacker.md similarity index 100% rename from docs/javascript/troubleshooting-when-using-webpacker.md rename to docs/deployment/troubleshooting-when-using-webpacker.md diff --git a/docs/troubleshooting/README.md b/docs/deployment/troubleshooting.md similarity index 98% rename from docs/troubleshooting/README.md rename to docs/deployment/troubleshooting.md index 6809acb192..b7e7403cd3 100644 --- a/docs/troubleshooting/README.md +++ b/docs/deployment/troubleshooting.md @@ -301,4 +301,4 @@ console.log(ReactOnRails.getComponents()); --- -**πŸ’‘ Tip:** Most issues are solved by ensuring your setup matches the [Quick Start Guide](../quick-start/README.md) exactly. +**πŸ’‘ Tip:** Most issues are solved by ensuring your setup matches the [Quick Start Guide](../getting-started/quick-start.md) exactly. diff --git a/docs/getting-started.md b/docs/getting-started.md index 50ec59a87c..15c24c6c5f 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,6 +1,6 @@ # Getting Started -> **πŸ’‘ Looking for the fastest way to get started?** Try our **[15-Minute Quick Start Guide](./quick-start/README.md)** instead. +> **πŸ’‘ Looking for the fastest way to get started?** Try our **[15-Minute Quick Start Guide](./getting-started/quick-start.md)** instead. ## Choose Your Starting Point @@ -8,15 +8,15 @@ The best way to understand React on Rails depends on your situation: ### πŸš€ **New to React on Rails?** -**β†’ [15-Minute Quick Start](./quick-start/README.md)** - Get your first component working fast +**β†’ [15-Minute Quick Start](./getting-started/quick-start.md)** - Get your first component working fast ### πŸ“± **Have an existing Rails app?** -**β†’ [Add to Existing App](./guides/installation-into-an-existing-rails-app.md)** - Integrate React on Rails +**β†’ [Add to Existing App](./getting-started/installation-into-an-existing-rails-app.md)** - Integrate React on Rails ### πŸ“š **Want comprehensive tutorial?** -**β†’ [Complete Tutorial](./guides/tutorial.md)** - Step-by-step with Redux and routing +**β†’ [Complete Tutorial](./getting-started/tutorial.md)** - Step-by-step with Redux and routing ### πŸ‘€ **Learn by example?** @@ -78,7 +78,7 @@ bin/dev static # ### Configuration -- Configure `config/initializers/react_on_rails.rb`. You can adjust some necessary settings and defaults. See file [docs/basics/configuration.md](./guides/configuration.md) for documentation of all configuration options. +- Configure `config/initializers/react_on_rails.rb`. You can adjust some necessary settings and defaults. See file [docs/basics/configuration.md](./api-reference/configuration.md) for documentation of all configuration options. - Configure `config/shakapacker.yml`. If you used the generator and the default Shakapacker setup, you don't need to touch this file. If you are customizing your setup, then consult the [spec/dummy/config/shakapacker.yml](https://github.com/shakacode/react_on_rails/tree/master/spec/dummy/config/shakapacker.yml) example or the official default [shakapacker.yml](https://github.com/shakacode/shakapacker/blob/master/lib/install/config/shakapacker.yml). - Most apps should rely on the Shakapacker setup for Webpack. Shakapacker v6+ includes support for Webpack version 5. @@ -135,13 +135,13 @@ With `auto_load_bundle: true`, and by placing your "exposed" components in the a - Automatically registers it for use. - Eliminates the need for manual pack configuration. -See [Auto-Bundling: File-System-Based Automated Bundle Generation](./guides/auto-bundling-file-system-based-automated-bundle-generation.md) +See [Auto-Bundling: File-System-Based Automated Bundle Generation](./core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md) Exposing your component in this way allows you to reference the component from a Rails view. You can expose as many components as you like, but their names must be unique. See below for the details of how you expose your components via the React on Rails Webpack configuration. You may call `ReactOnRails.register` many times. - `@some_props` can be either a hash or JSON string. This is an optional argument assuming you do not need to pass any options (if you want to pass options, such as `prerender: true`, but you do not want to pass any properties, simply pass an empty hash `{}`). **Props are automatically sanitized by React on Rails for security.** This will make the data available in your component: -- This is what your HelloWorld.js file might contain. The railsContext is always available for any parameters that you _always_ want available for your React components. It has _nothing_ to do with the concept of the [React Context](https://react.dev/reference/react/useContext). See [Render-Functions and the RailsContext](./guides/render-functions-and-railscontext.md) for more details on this topic. +- This is what your HelloWorld.js file might contain. The railsContext is always available for any parameters that you _always_ want available for your React components. It has _nothing_ to do with the concept of the [React Context](https://react.dev/reference/react/useContext). See [Render-Functions and the RailsContext](./core-concepts/render-functions-and-railscontext.md) for more details on this topic. ```js import React from 'react'; @@ -179,7 +179,7 @@ For details on techniques to use different code for client and server rendering, 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". Creating a render-function allows you to: -1. Access to the `railsContext`. See the [documentation for the railsContext](./guides/render-functions-and-railscontext.md) in terms of why you might need it. You **need** a Render-Function to access the `railsContext`. +1. Access to the `railsContext`. See the [documentation for the railsContext](./core-concepts/render-functions-and-railscontext.md) in terms of why you might need it. You **need** a Render-Function to access the `railsContext`. 2. Use the passed-in props to initialize a redux store or set up `react-router`. 3. Return different components depending on what's in the props. @@ -219,7 +219,7 @@ For server rendering, if you wish to return multiple HTML strings from a Render- } ``` -For details on using react_component_hash with react-helmet, see [our react-helmet documentation](./javascript/react-helmet.md). +For details on using react_component_hash with react-helmet, see [our react-helmet documentation](./building-features/react-helmet.md). ## Error Handling @@ -229,16 +229,16 @@ For details on using react_component_hash with react-helmet, see [our react-helm ## I18n React on Rails provides an option for automatic conversions of Rails `*.yml` locale files into `*.json` or `*.js`. -See the [How to add I18n](./guides/i18n.md) for a summary of adding I18n. +See the [How to add I18n](./building-features/i18n.md) for a summary of adding I18n. ## More Reading Depending on your goals, here's a progression of what to do next: -1. **[View Helpers API](./api/view-helpers-api.md)** - for more options of the `react_component` method. -2. **[Tutorial](./guides/tutorial.md)** - Comprehensive walkthrough of features with a real app. -3. **[Configuration](./guides/configuration.md)** - Details on every possible option you can configure. -4. **[Migration Guide](./guides/upgrading-react-on-rails.md)** - Upgrade advice for each version. +1. **[View Helpers API](./api-reference/view-helpers-api.md)** - for more options of the `react_component` method. +2. **[Tutorial](./getting-started/tutorial.md)** - Comprehensive walkthrough of features with a real app. +3. **[Configuration](./api-reference/configuration.md)** - Details on every possible option you can configure. +4. **[Migration Guide](./upgrading/upgrading-react-on-rails.md)** - Upgrade advice for each version. --- @@ -246,7 +246,7 @@ Depending on your goals, here's a progression of what to do next: ### Rails/React Integration Options -- **[Rails + Webpack Comparison](./guides/rails-webpacker-react-integration-options.md)** +- **[Rails + Webpack Comparison](./building-features/rails-webpacker-react-integration-options.md)** ### JavaScript/TypeScript Module System diff --git a/docs/guides/installation-into-an-existing-rails-app.md b/docs/getting-started/installation-into-an-existing-rails-app.md similarity index 88% rename from docs/guides/installation-into-an-existing-rails-app.md rename to docs/getting-started/installation-into-an-existing-rails-app.md index 4f26a58018..ab0d881c22 100644 --- a/docs/guides/installation-into-an-existing-rails-app.md +++ b/docs/getting-started/installation-into-an-existing-rails-app.md @@ -1,8 +1,8 @@ # Getting Started with an existing Rails app -**Also consult the instructions for installing on a fresh Rails app**, see the [React on Rails Basic Tutorial](./tutorial.md). +**Also consult the instructions for installing on a fresh Rails app**, see the [React on Rails Basic Tutorial](../getting-started/tutorial.md). -**If you have Rails 5 API only project**, first [convert the Rails 5 API only app to a normal Rails app](../rails/convert-rails-5-api-only-app.md). +**If you have Rails 5 API only project**, first [convert the Rails 5 API only app to a normal Rails app](../migrating/convert-rails-5-api-only-app.md). 1. Add the following to your Gemfile and `bundle install`. We recommend fixing the version of React on Rails, as you will need to keep the exact version in sync with the version in your `package.json` file. @@ -54,7 +54,7 @@ ## Installation -See the [Installation Overview](../additional-details/manual-installation-overview.md) for a concise set summary of what's in a React on Rails installation. +See the [Installation Overview](../advanced-topics/manual-installation-overview.md) for a concise set summary of what's in a React on Rails installation. ## NPM diff --git a/docs/additional-details/recommended-project-structure.md b/docs/getting-started/project-structure.md similarity index 100% rename from docs/additional-details/recommended-project-structure.md rename to docs/getting-started/project-structure.md diff --git a/docs/quick-start/README.md b/docs/getting-started/quick-start.md similarity index 86% rename from docs/quick-start/README.md rename to docs/getting-started/quick-start.md index 614cc6c4e9..4572da13ef 100644 --- a/docs/quick-start/README.md +++ b/docs/getting-started/quick-start.md @@ -160,24 +160,24 @@ Now that you have React on Rails working, here's what to explore next: ### Immediate Next Steps 1. **[Basic Configuration](../getting-started.md)** - Understand the setup -2. **[View Helpers API](../api/view-helpers-api.md)** - Learn all the options for `react_component` -3. **[Hot Module Replacement](../guides/hmr-and-hot-reloading-with-the-webpack-dev-server.md)** - Optimize your dev workflow +2. **[View Helpers API](../api-reference/view-helpers-api.md)** - Learn all the options for `react_component` +3. **[Hot Module Replacement](../building-features/hmr-and-hot-reloading-with-the-webpack-dev-server.md)** - Optimize your dev workflow ### Dive Deeper -1. **[Complete Tutorial](../guides/tutorial.md)** - Build a full app with Redux -2. **[Server-Side Rendering](../guides/react-server-rendering.md)** - Optimize for SEO and performance -3. **[Production Deployment](../guides/deployment.md)** - Deploy to production +1. **[Complete Tutorial](../getting-started/tutorial.md)** - Build a full app with Redux +2. **[Server-Side Rendering](../core-concepts/react-server-rendering.md)** - Optimize for SEO and performance +3. **[Production Deployment](../deployment/deployment.md)** - Deploy to production ### Advanced Features -1. **[Redux Integration](../javascript/react-and-redux.md)** - Manage application state -2. **[React Router](../javascript/react-router.md)** - Client-side routing -3. **[Code Splitting](../javascript/code-splitting.md)** - Optimize bundle size +1. **[Redux Integration](../building-features/react-and-redux.md)** - Manage application state +2. **[React Router](../building-features/react-router.md)** - Client-side routing +3. **[Code Splitting](../building-features/code-splitting.md)** - Optimize bundle size ## πŸ†˜ Need Help? -- **[Troubleshooting Guide](../troubleshooting/README.md)** - Common issues and solutions +- **[Troubleshooting Guide](../deployment/troubleshooting.md)** - Common issues and solutions - **[React + Rails Slack](https://reactrails.slack.com)** - Join our community - **[GitHub Issues](https://github.com/shakacode/react_on_rails/issues)** - Report bugs diff --git a/docs/guides/tutorial.md b/docs/getting-started/tutorial.md similarity index 98% rename from docs/guides/tutorial.md rename to docs/getting-started/tutorial.md index d2d65468c5..90d518b53f 100644 --- a/docs/guides/tutorial.md +++ b/docs/getting-started/tutorial.md @@ -330,8 +330,8 @@ versus with server rendering: For more details on server rendering, see: -- [Client vs. Server Rendering](./client-vs-server-rendering.md) -- [React Server Rendering](./react-server-rendering.md) +- [Client vs. Server Rendering](../core-concepts/client-vs-server-rendering.md) +- [React Server Rendering](../core-concepts/react-server-rendering.md) ## Moving from the Rails default `/app/javascript` to the recommended `/client` structure diff --git a/docs/guides/advanced/README.md b/docs/guides/advanced/README.md index 5f81b6f33a..9b0b1d866f 100644 --- a/docs/guides/advanced/README.md +++ b/docs/guides/advanced/README.md @@ -2,6 +2,6 @@ Advanced React on Rails features and patterns. -- [Auto-Bundling](../auto-bundling-file-system-based-automated-bundle-generation.md) -- [Server-Side Rendering](../react-server-rendering.md) -- [Performance Optimization](../webpack-configuration.md) +- [Auto-Bundling](../../core-concepts/auto-bundling-file-system-based-automated-bundle-generation.md) +- [Server-Side Rendering](../../core-concepts/react-server-rendering.md) +- [Performance Optimization](../../core-concepts/webpack-configuration.md) diff --git a/docs/home.md b/docs/home.md index 654496b238..a0747f56aa 100644 --- a/docs/home.md +++ b/docs/home.md @@ -2,19 +2,19 @@ ## Details -1. [Overview](./guides/react-on-rails-overview.md) +1. [Overview](./core-concepts/react-on-rails-overview.md) 1. [Getting Started](./getting-started.md) -1. [How React on Rails Works](./guides/how-react-on-rails-works.md) -1. [Webpack Configuration](./guides/webpack-configuration.md) -1. [View Helpers API](./api/view-helpers-api.md) +1. [How React on Rails Works](./core-concepts/how-react-on-rails-works.md) +1. [Webpack Configuration](./core-concepts/webpack-configuration.md) +1. [View Helpers API](./api-reference/view-helpers-api.md) 1. [Caching and Performance: React on Rails Pro](https://www.shakacode.com/react-on-rails-pro/). -1. [Deployment](./guides/deployment.md). +1. [Deployment](./deployment/deployment.md). ## Changes and Upgrades 1. [CHANGELOG.md](https://github.com/shakacode/react_on_rails/tree/master/CHANGELOG.md) -2. [Upgrading React on Rails](./guides/upgrading-react-on-rails.md) -3. [Troubleshooting Build Errors](./javascript/troubleshooting-build-errors.md) +2. [Upgrading React on Rails](./upgrading/upgrading-react-on-rails.md) +3. [Troubleshooting Build Errors](./deployment/troubleshooting-build-errors.md) ## Example Apps diff --git a/docs/javascript/node-dependencies-and-npm.md b/docs/javascript/node-dependencies-and-npm.md deleted file mode 100644 index 2abd824c11..0000000000 --- a/docs/javascript/node-dependencies-and-npm.md +++ /dev/null @@ -1,20 +0,0 @@ -# Node Dependencies, NPM, and Yarn - -## Updating - -You can check for outdated versions of packages with `yarn outdated` in your `client` directory. - -To upgrade package version, use `yarn upgrade [package]`. To update all dependencies, use `yarn upgrade`. - -Confirm that the hot replacement dev server and the Rails server both work. - -## Adding New Dependencies - -Typically, you can add your Node dependencies as you normally would. - -```bash -cd client -yarn add module_name@version -# or -# yarn add --dev module_name@version -``` diff --git a/docs/javascript/angular-js-integration-migration.md b/docs/migrating/angular-js-integration-migration.md similarity index 100% rename from docs/javascript/angular-js-integration-migration.md rename to docs/migrating/angular-js-integration-migration.md diff --git a/docs/rails/convert-rails-5-api-only-app.md b/docs/migrating/convert-rails-5-api-only-app.md similarity index 87% rename from docs/rails/convert-rails-5-api-only-app.md rename to docs/migrating/convert-rails-5-api-only-app.md index 80f8327df7..82e226af38 100644 --- a/docs/rails/convert-rails-5-api-only-app.md +++ b/docs/migrating/convert-rails-5-api-only-app.md @@ -16,4 +16,4 @@ Rails will start creating the app and will skip the files you have already creat 3. If it is removeing some of your code then press "n" and add all additions manually ``` -3. Run `bundle install` and follow [the instructions for installing into an existing Rails app](../guides/installation-into-an-existing-rails-app.md) +3. Run `bundle install` and follow [the instructions for installing into an existing Rails app](../getting-started/installation-into-an-existing-rails-app.md) diff --git a/docs/additional-details/migrating-from-react-rails.md b/docs/migrating/migrating-from-react-rails.md similarity index 100% rename from docs/additional-details/migrating-from-react-rails.md rename to docs/migrating/migrating-from-react-rails.md diff --git a/docs/misc/articles.md b/docs/misc/articles.md index 88b45b47d9..0d75db3b56 100644 --- a/docs/misc/articles.md +++ b/docs/misc/articles.md @@ -6,7 +6,7 @@ - [Webpacker Lite: Why Fork Webpacker?](https://blog.shakacode.com/webpacker-lite-why-fork-webpacker-f0a7707fac92) - [React on Rails, 2000+ 🌟 Stars](https://medium.com/shakacode/react-on-rails-2000-stars-32ff5cfacfbf#.6gmfb2gpy) - [The React on Rails Doctrine](https://medium.com/@railsonmaui/the-react-on-rails-doctrine-3c59a778c724) -- [Simple Tutorial](../guides/tutorial.md). +- [Simple Tutorial](../getting-started/tutorial.md). ## Videos diff --git a/docs/javascript/asset-pipeline.md b/docs/misc/asset-pipeline.md similarity index 100% rename from docs/javascript/asset-pipeline.md rename to docs/misc/asset-pipeline.md diff --git a/docs/javascript/credits.md b/docs/misc/credits.md similarity index 100% rename from docs/javascript/credits.md rename to docs/misc/credits.md diff --git a/docs/misc/doctrine.md b/docs/misc/doctrine.md index a893bd9a5d..766601ab81 100644 --- a/docs/misc/doctrine.md +++ b/docs/misc/doctrine.md @@ -4,7 +4,7 @@ By Justin Gordon, January 26, 2016 This document is an extension and complement to [The Rails Doctrine](http://rubyonrails.org/doctrine/). If you haven't read that document, I suggest you do so first. -To paraphrase the [React on Rails Overview](../guides/react-on-rails-overview.md), the project objective is to provide an opinionated and optimal framework for integrating **Ruby on Rails** with modern JavaScript tooling and libraries. +To paraphrase the [React on Rails Overview](../core-concepts/react-on-rails-overview.md), the project objective is to provide an opinionated and optimal framework for integrating **Ruby on Rails** with modern JavaScript tooling and libraries. When considering what goes into **react_on_rails**, we ask ourselves, is the functionality related to the intersection of using Rails and with modern JavaScript? A good example is view helper integration of React components on a Rails view. If the answer is yes, then the functionality belongs right here. diff --git a/docs/misc/updating-dependencies.md b/docs/misc/updating-dependencies.md new file mode 100644 index 0000000000..c58dc4dc4a --- /dev/null +++ b/docs/misc/updating-dependencies.md @@ -0,0 +1,75 @@ +# Updating Dependencies + +If you frequently update dependencies in small batches, you will avoid large and painful updates later. Then again, if you don't have good test coverage, it's hazardous to update dependencies at any time. + +## Ruby + +Delete any unwanted version constraints from your Gemfile and run: + +```bash +bundle update +``` + +## Node/Yarn + +### Checking for Outdated Packages + +Check for outdated versions of packages: + +```bash +cd client +yarn outdated +``` + +Read CHANGELOGs of major updated packages before you update. You might not be ready for some updates. + +### Updating All Dependencies + +**Option 1: Using npm-check-updates (Recommended)** + +1. Install [npm-check-updates](https://www.npmjs.com/package/npm-check-updates) +2. Run these commands. You may or may not need to `rm -rf` your `node_modules` directory. + + ```bash + cd client + ncu -u -a + yarn + ``` + +Some combinations that I often run: + +- Remove old installed `node_modules` so you only get what corresponds to `package.json`: + + ```bash + ncu -u -a && rm -rf node_modules && yarn + ``` + +**Option 2: Using yarn upgrade** + +To update all dependencies: + +```bash +cd client +yarn upgrade +``` + +To upgrade a specific package: + +```bash +yarn upgrade [package] +``` + +### Adding New Dependencies + +Typically, you can add your Node dependencies as you normally would: + +```bash +cd client +yarn add module_name@version +# or for dev dependencies +yarn add --dev module_name@version +``` + +### Verify After Updates + +Confirm that the hot replacement dev server and the Rails server both work after updating dependencies. diff --git a/docs/javascript/converting-from-custom-webpack-config-to-rails-webpacker-config.md b/docs/outdated/converting-from-custom-webpack-config-to-rails-webpacker-config.md similarity index 100% rename from docs/javascript/converting-from-custom-webpack-config-to-rails-webpacker-config.md rename to docs/outdated/converting-from-custom-webpack-config-to-rails-webpacker-config.md diff --git a/docs/additional-details/tips-for-usage-with-sp6.md b/docs/outdated/tips-for-usage-with-sp6.md similarity index 100% rename from docs/additional-details/tips-for-usage-with-sp6.md rename to docs/outdated/tips-for-usage-with-sp6.md diff --git a/docs/additional-details/upgrade-webpacker-v3-to-v4.md b/docs/outdated/upgrade-webpacker-v3-to-v4.md similarity index 100% rename from docs/additional-details/upgrade-webpacker-v3-to-v4.md rename to docs/outdated/upgrade-webpacker-v3-to-v4.md diff --git a/docs/javascript/webpack.md b/docs/outdated/webpack.md similarity index 100% rename from docs/javascript/webpack.md rename to docs/outdated/webpack.md diff --git a/docs/planning/docs-improvement/01-problem-analysis.md b/docs/planning/docs-improvement/01-problem-analysis.md new file mode 100644 index 0000000000..38943e6c4b --- /dev/null +++ b/docs/planning/docs-improvement/01-problem-analysis.md @@ -0,0 +1,1264 @@ +# React on Rails Documentation - Detailed Problem Analysis + +**Date:** September 30, 2025 +**Analyst:** Ihab +**Goal:** Identify specific issues preventing users from having a smooth, professional documentation experience + +--- + +## 1. Information Architecture Problems + +### 1.1 Unclear Category Hierarchy + +**Problem:** The current 11-category structure lacks clear hierarchy and logical grouping. + +**Current Categories** (defined in `gatsby-node.js:31-44`): + +```javascript +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:** + +1. **"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) + - These belong in different categories based on user intent + +2. **"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) + +3. **"Guides" is too broad** - Contains 18+ files ranging from: + - Installation (`installation-into-an-existing-rails-app.md`) + - Tutorials (`tutorial.md`) + - Configuration (`configuration.md`) + - Advanced features (`streaming-server-rendering.md`) + - How-tos (`how-to-conditionally-server-render-based-on-device-type.md`) + +**Impact:** + +- Users don't know where to look for specific information +- No clear progression from beginner to advanced +- Similar topics scattered across multiple categories + +**Source Files:** + +- Category definition: `/home/ihab/ihab/work/shakacode/sc-website/gatsby-node.js:31-44` +- Sidebar rendering: `/home/ihab/ihab/work/shakacode/sc-website/src/styleguide/page-components/DocArticle/DocSidebar.tsx:178-253` + +--- + +### 1.2 Multiple, Conflicting Entry Points + +**Problem:** Four different "starting point" documents create confusion about where to begin. + +**Entry Points Found:** + +1. **`docs/README.md`** (173 lines) + + - Comprehensive navigation hub + - Learning paths section (lines 13-36) + - Popular use cases table (lines 40-49) + - Complete TOC (lines 107-173) + - **Issue:** Too long for a README, actually a full navigation page + +2. **`docs/home.md`** (29 lines) + + - Minimal landing page + - Just links to other docs + - **Issue:** Unclear purpose - why exists separately from README? + +3. **`docs/getting-started.md`** (254 lines) + + - Installation instructions + - System requirements + - Basic usage examples + - **Issue:** Mixed beginner onboarding + reference material + +4. **`docs/quick-start/README.md`** (location referenced but not yet examined) + - Promised "15-minute" quick start + - **Issue:** Buried in subdirectory, not prominently featured + +**Confusion Points:** + +From `README.md:9-11`: + +```markdown +**β†’ [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`: + +```markdown +> **πŸ’‘ 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:** + +- New users see 4 different "start here" options +- Each document has different content and depth +- No clear answer to "where do I actually start?" +- Cross-references between docs create circular navigation + +--- + +### 1.3 Mixing User-Facing and Internal Documentation + +**Problem:** Navigation includes docs meant only for contributors, not end users. + +**Contributor Docs in Main Navigation:** + +1. **`contributor-info/` folder** - 5 files: + + - `linters.md` - Linting setup for contributors + - `coding-agents-guide.md` - Guide for AI coding assistants + - `errors-with-hooks.md` - Git hooks troubleshooting + - `generator-testing.md` - Testing generators during development + - `releasing.md` - Release process for maintainers + - `pull-requests.md` - PR guidelines + +2. **Planning documents visible:** + + - `docs/planning/DOCUMENTATION_IMPROVEMENT_PLAN.md` + - `docs/planning/DOCS_PR_SUMMARY.md` + - These are internal planning docs, not user documentation + +3. **Root-level internal docs:** + - `docs/MONOREPO_MERGER_PLAN.md` (32KB) + - `docs/MONOREPO_MERGER_PLAN_REF.md` + - `docs/DIRECTORY_LICENSING.md` + - Internal project management documents + +**Impact:** + +- Cluttered navigation overwhelms users +- Professional appearance undermined by internal notes +- Users may read contributor docs and get confused +- Signal-to-noise ratio is poor + +**Evidence:** +From `gatsby-node.js:185-194`, the build system includes ALL markdown files: + +```javascript +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/ +}); +``` + +--- + +### 1.4 Outdated Content Visible in Navigation + +**Problem:** A category called "Outdated" is visible in primary navigation. + +**Outdated Folder Contents:** + +- `docs/outdated/deferred-rendering.md` +- `docs/outdated/webpack-v1-notes.md` +- `docs/outdated/rails3.md` +- `docs/outdated/rails-assets.md` +- `docs/outdated/rails-assets-relative-paths.md` + +**Current Treatment:** +From `gatsby-node.js:31-44`, "Outdated" is the last category but still included: + +```javascript +const reactOnRailsDocsFoldersOrder = [ + // ... other categories + 'Outdated', // ← Still in navigation! +]; +``` + +**Issues:** + +1. **Confusing for users:** Why show documentation that's explicitly marked outdated? +2. **Unprofessional appearance:** Competitors don't expose deprecated docs in main navigation +3. **Decision fatigue:** Users don't know if current docs might also be outdated +4. **SEO pollution:** Old docs may rank in search results + +**Better Practices (from competitors):** + +- **Next.js:** Outdated docs moved to versioned URLs (`nextjs.org/docs/pages/...` for old Pages Router) +- **TanStack:** Clear version switcher, old versions in separate navigation trees +- **Rails Guides:** Each version has separate docs site (`guides.rubyonrails.org/v7.0/...`) + +**Impact:** + +- Undermines confidence in documentation quality +- Wastes user time exploring irrelevant docs +- Poor first impression for evaluating developers + +--- + +## 2. Beginner Onboarding Gaps + +### 2.1 Concepts Not Explained Before Usage + +**Problem:** Documentation jumps into implementation details without explaining foundational concepts. + +**Example 1: Server-Side Rendering (SSR)** + +From `getting-started.md:93-97`: + +````erb +- **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:** + +- What is "bundling" in the first place? +- What's the difference between auto-bundling and manual bundling? +- What are "packs"? (Assumed knowledge from Webpacker) +- Why does component registration matter? +- What happens under the hood? +- When should I NOT use auto-bundling? + +The comparison between manual and auto-bundling helps, but assumes user understands webpack concepts. + +--- + +**Example 3: Render Functions** + +From `getting-started.md:178-204`: + +```markdown +## 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:** + +- What is a "render-function" conceptually? +- Why would I need one vs. a regular component? +- How is this different from React's render function? +- Custom terminology ("render-function") not explained before use + +--- + +**Pattern Observed:** + +The docs follow a "reference manual" pattern: + +1. Here's a feature +2. Here's the syntax +3. Here's an example + +Instead of a "learning guide" pattern: + +1. Here's a problem you might have +2. Here's how this feature solves it +3. Here's when to use it +4. Here's how to implement it + +**Impact:** + +- High cognitive load for beginners +- Users copy-paste without understanding +- Harder to debug when things go wrong +- Users can't make informed architectural decisions + +--- + +### 2.2 Installation Instructions Scattered + +**Problem:** Installation steps are fragmented across multiple documents without clear ownership. + +**Installation Information Locations:** + +1. **`getting-started.md:38-76`** - "Basic Installation" + + - Rails app creation + - Shakapacker prerequisites + - Generator command + - Starting the app + +2. **`guides/installation-into-an-existing-rails-app.md`** - Full guide + + - (Not yet examined but referenced multiple times) + - Seems to be the canonical installation guide + - But not clearly marked as THE starting point + +3. **`quick-start/README.md`** - Quick installation + + - Promised "15-minute" path + - Unclear how it differs from other guides + +4. **`README.md:44`** - Installation link in table: + +```markdown +| **Add React to existing Rails app** | [Installation Guide](./guides/installation-into-an-existing-rails-app.md) | +``` + +5. **`guides/tutorial.md`** - Tutorial installation + - Likely has its own installation steps + - May differ from other guides + +**Inconsistencies:** + +From `getting-started.md:50-56`: + +```bash +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:** + +- Why must I commit before running generator? +- What happens if I don't commit? +- What is `--ignore-warnings`? +- Why is version hardcoded to 16.0.0? + +These concerns aren't addressed in context. + +**Impact:** + +- Users don't know which guide to follow +- Different guides may have conflicting steps +- Hard to maintain consistency across guides +- Users may skip crucial setup steps + +--- + +### 2.3 Missing Prerequisites and Assumptions + +**Problem:** Documentation assumes knowledge that beginners may not have. + +**Assumed Knowledge Examples:** + +**1. Shakapacker (critical dependency)** + +From `getting-started.md:36`: + +```markdown +> **Don't have Shakapacker?** It's the modern replacement for Webpacker and required for React on Rails. +``` + +**Issues:** + +- What is Shakapacker? (one sentence doesn't explain it) +- Why is it required? +- What if I'm using Vite or another bundler? +- How do I install it? +- Link to Shakapacker docs, but user leaves React on Rails docs + +**2. Webpack Configuration** + +Multiple references to webpack throughout docs assume user understanding: + +- `docs/guides/webpack-configuration.md` - Entire guide about webpack +- `docs/javascript/webpack.md` - Another webpack guide +- References to "packs", "bundles", "entry points" + +No explanation of: + +- What webpack is +- Why React on Rails needs it +- How it integrates with Rails + +**3. Rails Asset Pipeline** + +From `getting-started.md:82-83`: + +```markdown +- 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:** + +- User knows what Rails initializers are +- User understands YAML configuration +- User knows where config files live +- User can debug if generator didn't create these files + +**4. Node.js Ecosystem** + +From `getting-started.md:34`: + +```markdown +βœ… **Node.js 18+** +``` + +**Missing information:** + +- How to install Node.js +- Why this specific version? +- How to manage multiple Node versions +- What if my Rails app uses a different version? + +**Impact:** + +- Beginners get stuck on prerequisites +- Support burden increases with basic questions +- Users abandon setup process +- Poor first impression compared to competitors with better onboarding + +--- + +## 3. Content Organization Issues + +### 3.1 No Clear Progressive Disclosure + +**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: + +```markdown +## πŸ“– 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:** + +1. **No difficulty indicators:** All topics appear equal in complexity +2. **No prerequisites shown:** Can't tell what to read first +3. **No estimated time:** Users can't plan their learning +4. **No "required vs. optional":** Everything seems equally important + +**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 SSR +- `docs/guides/streaming-server-rendering.md` - Advanced SSR +- Both in same "Guides" category with no indication of order + +--- + +**Better 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: + +1. "Streaming Server Rendering" (advanced Pro feature) +2. "How to conditionally server render based on device type" (advanced how-to) +3. "React Server Rendering" (basic concept) + +Because all are in "Guides" with alphabetical ordering. + +**Impact:** + +- Beginners get overwhelmed by advanced topics +- Advanced users frustrated by basic content mixed in +- No clear path from "beginner" to "expert" +- Higher abandonment rate during learning + +--- + +### 3.2 API Reference Mixed with Guides + +**Problem:** Reference documentation not clearly separated from learning guides. + +**Current "API" Category:** + +From `docs/api/` folder: + +- `README.md` - API overview +- `view-helpers-api.md` - `react_component` helper reference +- `redux-store-api.md` - Redux store API +- `javascript-api.md` - JavaScript API reference + +**BUT, API information also appears in:** + +1. **`getting-started.md:86-90`** - Shows `react_component` usage: + +```erb +<%= react_component("HelloWorld", props: @some_props) %> +``` + +2. **`getting-started.md:206-222`** - Documents `react_component_hash`: + +```markdown +## 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). +``` + +3. **`guides/configuration.md`** - Config API reference +4. **`guides/render-functions-and-railscontext.md`** - API for render functions + +**Problems:** + +1. **Duplication:** Same API documented in multiple places with potential inconsistencies +2. **No single source of truth:** Where do I look for definitive API docs? +3. **Mixed purposes:** Guides teach concepts, references list options - both needed but should be separate +4. **Discoverability:** If API is split across docs, users miss options + +**Example of Confusion:** + +User wants to know all options for `react_component` helper: + +- Should they read `getting-started.md`? +- Or `api/view-helpers-api.md`? +- Or both? +- Are they consistent? + +--- + +**Better Pattern:** + +**Guides (Learning):** + +```markdown +# 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):** + +```markdown +# 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:** + +- Users can't quickly look up API options +- Risk of following outdated examples in guides +- Harder to maintain documentation +- Professional developers frustrated by poor reference docs + +--- + +### 3.3 Testimonials and Marketing in Technical Docs + +**Problem:** Marketing content mixed with technical documentation creates unprofessional impression. + +**Current Structure:** + +From `gatsby-node.js:41-42`: + +```javascript +"Testimonials", +"Outdated", +``` + +"Testimonials" is a top-level category in the technical documentation. + +**Testimonials Folder Contents:** + +- `docs/testimonials/testimonials.md` - List of testimonials +- `docs/testimonials/hvmn.md` - HVMN case study +- `docs/testimonials/resortpass.md` - ResortPass case study + +**Issues:** + +1. **Wrong audience:** Users reading technical docs want to solve problems, not read testimonials +2. **Wrong context:** Testimonials belong on marketing site, not in documentation navigation +3. **Navigation clutter:** Takes up space in sidebar that could be used for technical content +4. **Unprofessional:** Major frameworks don't mix these concerns + +**Where Users Expect Testimonials:** + +- Main marketing site homepage +- Dedicated "Case Studies" section on website +- "Why Choose React on Rails" landing page +- NOT in technical documentation sidebar + +**Comparison with Competitors:** + +**Next.js:** + +- Technical docs: `nextjs.org/docs` +- Showcase/testimonials: `nextjs.org/showcase` +- Clearly separated + +**Rails Guides:** + +- Technical docs: `guides.rubyonrails.org` +- Testimonials: `rubyonrails.org/` (marketing site) +- Never mixed + +**TanStack:** + +- Docs: `tanstack.com/router/latest/docs` +- No testimonials in technical docs +- Marketing content on separate pages + +--- + +**What to Do with Testimonials:** + +1. **Move to marketing site:** ShakaCode website should host these +2. **Create "Showcase" page:** Separate from docs navigation +3. **Link from introduction:** "See who uses React on Rails" β†’ external page +4. **Remove from docs navigation:** Keep technical docs technical + +**Impact:** + +- Reduced professional credibility +- Distraction from learning and reference tasks +- Longer navigation lists with less relevant content +- Inconsistent with industry standards + +--- + +### 3.4 Inconsistent Document Depth and Style + +**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: + +```markdown +# 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 + +- Installation +- Configuration +- Usage examples +- API reference +- Render functions +- Error handling +- I18n +- Additional resources + +Tries to be everything: tutorial, reference, guide, and quickstart. + +`docs/README.md` - 173 lines + +- Navigation hub +- Learning paths +- Use case table +- Complete TOC +- Multiple entry points + +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`: + +```markdown +> **πŸ’‘ 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: + +```markdown +## 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`: + +```markdown +βœ… **🚨 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`: + +```markdown +| I want to... | Go here | +| ----------------------------------- | ------------------------------------------------------------------------- | +| **Add React to existing Rails app** | [Installation Guide](./guides/installation-into-an-existing-rails-app.md) | +``` + +--- + +**Impact:** + +- Users don't know what to expect from each document +- Some docs overwhelming, others too brief +- Inconsistent voice hurts professionalism +- Hard to maintain as team grows +- No clear document templates or guidelines + +--- + +**Better Pattern:** + +Clear document types with defined purposes: + +1. **Tutorial:** Step-by-step, conversational, builds something, 20-40 min +2. **Guide:** Explains concept deeply, includes examples, 10-15 min read +3. **How-To:** Solves specific problem, terse, 5 min read +4. **Reference:** Lists all options, technical, quick lookup + +Each type has: + +- Consistent structure +- Expected length +- Appropriate tone +- Clear template + +--- + +## 4. Technical Issues + +### 4.1 Broken Internal Links Risk + +**Problem:** Documentation uses relative links that may break during site reorganization. + +**Examples of Relative Link Patterns:** + +From `getting-started.md`: + +```markdown +See file [docs/basics/configuration.md](./guides/configuration.md) +``` + +From `README.md`: + +```markdown +- **[Quick Start](./quick-start/README.md)** +- **[Tutorial](./guides/tutorial.md)** +- **[Installation Guide](./guides/installation-into-an-existing-rails-app.md)** +``` + +**Risks:** + +1. **Gatsby transformation:** Website build (`gatsby-node.js`) transforms these paths: + +```javascript +// From: ./guides/tutorial.md +// To: /react-on-rails/docs/guides/tutorial/ +``` + +2. **Link checking:** No automated link validation in CI +3. **Refactoring risk:** Moving files breaks links in multiple places +4. **Cross-references:** Complex web of interdependencies + +**Evidence of Potential Issues:** + +From `docs/planning/DOCUMENTATION_IMPROVEMENT_PLAN.md` exists but may have broken links to docs that were moved. + +--- + +### 4.2 Images and Assets Organization + +**Problem:** Image references and asset management unclear. + +From `getting-started.md:168`: + +```markdown +![Basic Hello World Example](./images/bundle-splitting-hello-world.png) +``` + +**Questions:** + +- Where are images stored? (`docs/images/` folder exists) +- How are they served on the website? +- Are images optimized for web? +- Are there broken image links? +- How to add new images? + +--- + +### 4.3 Search and Discoverability + +**Problem:** No clear search functionality or metadata for discovery. + +**Observations:** + +1. **No frontmatter:** Most docs lack YAML frontmatter: + +```markdown +--- +title: Getting Started +description: Install React on Rails +keywords: [installation, setup, rails] +--- +``` + +2. **No tags/categories in files:** Categories only in website code +3. **No search optimization:** Content not structured for search +4. **No related docs links:** Each doc is isolated + +**Impact:** + +- Users can't search documentation effectively +- Hard to discover related content +- Poor SEO for documentation pages +- Rely entirely on navigation structure + +--- + +## 5. Missing Content + +### 5.1 No "Why React on Rails?" + +**Critical Missing Page:** Introduction explaining the value proposition. + +**What's Missing:** + +1. **Problem statement:** + + - Why integrate React with Rails? + - What problems does React on Rails solve? + - What are the alternatives? + +2. **Comparison with alternatives:** + + - vs. plain Rails views + - vs. separate React frontend + - vs. react-rails gem + - vs. Hotwire/Turbo + - vs. Inertia.js + +3. **When to use / when not to use:** + + - Best fit use cases + - When to choose something else + - Migration scenarios + +4. **Architecture overview:** + - How does it work at a high level? + - What's the request/response flow? + - Where does React run? (client/server) + +**Current Situation:** + +`docs/guides/react-on-rails-overview.md` exists but not clearly positioned as THE introduction. + +**Impact:** + +- Developers can't make informed decisions +- No clear pitch for managers/stakeholders +- Users jump into "how" before understanding "why" +- Harder to advocate for using React on Rails in teams + +--- + +### 5.2 No Migration Paths + +**Problem:** Sparse guidance on migrating existing applications. + +**What Exists:** + +- `docs/additional-details/migrating-from-react-rails.md` - Only one migration guide +- `docs/guides/upgrading-react-on-rails.md` - Version upgrades + +**What's Missing:** + +1. **Migrating from plain Rails views:** + + - How to gradually introduce React + - Which views to convert first + - Hybrid approach patterns + +2. **Migrating from separate React frontend:** + + - Moving from React SPA to React on Rails + - Sharing components + - Authentication/session handling + +3. **Migrating from Hotwire/Turbo:** + + - When to switch + - How to coexist + - Gradual migration strategy + +4. **Version-to-version migration:** + - Breaking changes documentation + - Automated migration tools + - Rollback strategies + +**Impact:** + +- Teams with existing apps hesitant to adopt +- No clear path from evaluation to production +- Risk assessment difficult +- Support burden with migration questions + +--- + +### 5.3 No Troubleshooting Decision Tree + +**Problem:** Troubleshooting docs are scattered without clear starting point. + +**Current Troubleshooting Docs:** + +- `docs/troubleshooting/README.md` +- `docs/javascript/troubleshooting-build-errors.md` +- `docs/javascript/troubleshooting-when-using-shakapacker.md` +- `docs/javascript/troubleshooting-when-using-webpacker.md` + +**What's Missing:** + +1. **Diagnostic flow:** + + ``` + Issue β†’ Is it build-time or run-time? + β†’ Client or server? + β†’ Webpack or Rails? + β†’ [Specific guide] + ``` + +2. **Common error messages:** + + - Database of actual error text + - Direct solutions + - Search optimization + +3. **Debugging tools:** + + - How to enable trace mode + - How to inspect SSR output + - Browser devtools setup + +4. **Getting help:** + - What info to provide + - Where to ask + - How to create minimal reproduction + +**Impact:** + +- Users stuck without clear next steps +- Repeated support questions +- Frustration during debugging +- Higher abandonment rate + +--- + +## 6. Competitive Analysis Gaps + +### 6.1 Compared to Next.js Docs + +**Next.js Strengths We're Missing:** + +1. **Clear learning path:** + + - Installation β†’ Creating routes β†’ Data fetching β†’ Deployment + - Each step builds on previous + - Time estimates provided + +2. **Interactive examples:** + + - Code playground integration + - Copy-paste ready examples + - Visual diagrams + +3. **Version switcher:** + + - App Router vs Pages Router clearly separated + - Easy to switch between versions + - Migration guides prominent + +4. **Rich media:** + - Diagrams explaining concepts + - Video tutorials + - GIFs showing features + +**Source:** https://nextjs.org/docs + +--- + +### 6.2 Compared to TanStack Docs + +**TanStack Strengths We're Missing:** + +1. **Clear difficulty levels:** + + - πŸ”° Quick Start (beginner) + - πŸ“˜ Guide (intermediate) + - πŸ“• API Reference (lookup) + +2. **Framework adapters clearly separated:** + + - React, Vue, Svelte, etc. in tabs + - Don't mix framework-specific advice + +3. **Examples repository:** + + - Linked examples for every major feature + - Can clone and run locally + - Multiple implementation approaches shown + +4. **API documentation generated from code:** + - Always in sync with implementation + - TypeScript types shown + - Inline JSDoc comments + +**Source:** https://tanstack.com/router/latest/docs + +--- + +### 6.3 Compared to Rails Guides + +**Rails Guides Strengths We're Missing:** + +1. **Consistent structure:** + + - Every guide follows same template + - Predictable sections + - Known length and depth + +2. **Glossary:** + + - Terms defined + - Linked throughout docs + - No assumed knowledge + +3. **Contributing guide prominent:** + + - Clear how to improve docs + - Documentation standard + - Review process + +4. **Edge guides separate:** + - Cutting-edge features clearly marked + - Stable vs experimental obvious + - Version compatibility clear + +**Source:** https://guides.rubyonrails.org + +--- + +## Summary of Critical Issues + +**Highest Impact Problems:** + +1. ⚠️ **Multiple entry points with no clear starting path** (Section 1.2) +2. ⚠️ **Concepts not explained before usage** (Section 2.1) +3. ⚠️ **Unclear category hierarchy** (Section 1.1) +4. ⚠️ **No "Why React on Rails?" introduction** (Section 5.1) +5. ⚠️ **Installation scattered across multiple docs** (Section 2.2) + +**Secondary Problems:** + +6. Contributor docs mixed with user docs (Section 1.3) +7. Outdated content in navigation (Section 1.4) +8. No progressive disclosure (Section 3.1) +9. Testimonials in technical docs (Section 3.3) +10. Inconsistent document styles (Section 3.4) + +**Technical Debt:** + +11. Link management risk (Section 4.1) +12. No search metadata (Section 4.3) +13. Missing migration guides (Section 5.2) +14. Scattered troubleshooting (Section 5.3) + +--- + +## Next Steps + +This analysis will inform: + +1. Information architecture redesign proposal +2. Content reorganization plan +3. Writing style guide +4. Documentation templates +5. Migration strategy + +**Priority Order:** + +1. Fix critical user journey (entry points, onboarding) +2. Restructure categories (IA redesign) +3. Hide internal docs (contributor/outdated) +4. Standardize document types (templates) +5. Add missing content (why, migration) diff --git a/docs/planning/docs-improvement/02-pr-1813-comparison.md b/docs/planning/docs-improvement/02-pr-1813-comparison.md new file mode 100644 index 0000000000..910ef73989 --- /dev/null +++ b/docs/planning/docs-improvement/02-pr-1813-comparison.md @@ -0,0 +1,864 @@ +# PR #1813 Comparison: What Was Fixed vs. What Remains + +**Date:** September 30, 2025 +**PR Reference:** [#1813 - Comprehensive documentation improvements](https://github.com/shakacode/react_on_rails/pull/1813) +**Merged:** September 23, 2025 by Justin Gordon + +--- + +## Executive Summary + +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`. + +--- + +## βœ… What PR #1813 Successfully Fixed + +### 1. Quick Start Guide Created βœ… + +**Problem Addressed:** Section 2.1 - Missing fast onboarding path + +**What Was Done:** + +- Created `docs/quick-start/README.md` (212 lines) +- 15-minute quick start with clear steps +- Modern auto-bundling patterns emphasized +- Step-by-step with time estimates + +**Impact:** + +- βœ… Users now have a fast path to first success +- βœ… Clear progression through installation β†’ running β†’ editing +- βœ… Modern best practices (auto-bundling) featured + +**Remaining Gaps:** + +- Quick start still buried in subdirectory (not in main navigation prominently) +- Still referenced as "one option" rather than THE starting point + +--- + +### 2. Troubleshooting Guide Created βœ… + +**Problem Addressed:** Section 5.3 - Scattered troubleshooting + +**What Was Done:** + +- Created `docs/troubleshooting/README.md` (304 lines) +- Organized by problem type (Installation, Build, Runtime, SSR, Performance) +- Quick diagnosis table at top +- Common error messages with solutions + +**Impact:** + +- βœ… Centralized troubleshooting resource +- βœ… Clear decision tree for diagnosis +- βœ… Specific error messages documented + +**Quality:** +Strong execution. This addresses the troubleshooting fragmentation well. + +--- + +### 3. Documentation Hub Created βœ… + +**Problem Addressed:** Section 1.2 - Multiple conflicting entry points + +**What Was Done:** + +- Created `docs/README.md` (172 lines) +- Learning paths section +- Popular use cases table +- Complete table of contents + +**Impact:** + +- βœ… Single navigation hub exists +- βœ… Multiple user journeys acknowledged +- βœ… Better organization than before + +**Remaining Issues:** + +- Doesn't solve the fundamental problem of 4 entry points +- Now we have: `README.md`, `docs/README.md`, `docs/home.md`, `docs/getting-started.md`, `docs/quick-start/README.md` +- More coordination between these, but still confusing which is THE starting point + +--- + +### 4. Broken Links Fixed βœ… + +**Problem Addressed:** Section 4.1 - Link management risk + +**What Was Done:** + +- Fixed 27+ broken internal links +- Updated image paths +- Corrected anchor links +- Added automated link checking CI (PR #1800) + +**Impact:** + +- βœ… Users won't hit 404s +- βœ… CI prevents future link rot +- βœ… Navigation more reliable + +**Quality:** +Excellent technical improvement with future-proofing. + +--- + +### 5. Version Requirements Standardized βœ… + +**Problem Addressed:** Section 2.3 - Inconsistent prerequisites + +**What Was Done:** + +- Reconciled version specs across all docs +- Consistent messaging: Shakapacker 6+ (7+ recommended), Ruby 3.0+, Rails 5.2+, Node 18+ +- Removed conflicting "Ruby 2.7+ supported" references +- Prominent version warnings with 🚨 emoji + +**Impact:** + +- βœ… Clear system requirements +- βœ… No more conflicting info +- βœ… Users know what they need upfront + +--- + +### 6. Visual Improvements βœ… + +**Problem Addressed:** Section 3.4 - Inconsistent formatting + +**What Was Done:** + +- Consistent emoji usage (πŸš€, 🎯, βœ…, πŸ’‘, etc.) +- Tables for comparison and navigation +- Callout boxes with > quotes +- Better heading hierarchy +- Code blocks with language tags + +**Impact:** + +- βœ… More scannable documents +- βœ… Visual hierarchy clearer +- βœ… Professional appearance + +**Quality:** +Good improvement, though not comprehensive across all docs. + +--- + +### 7. AI Agent Instructions βœ… + +**Problem Addressed:** (Not in our analysis - bonus improvement) + +**What Was Done:** + +- Created `AI_AGENT_INSTRUCTIONS.md` +- Proper installation order for coding agents +- Common pitfalls documented + +**Impact:** + +- βœ… Better AI-assisted development experience +- βœ… Reduces errors from incorrect agent assumptions + +--- + +### 8. Content Modernization βœ… + +**Problem Addressed:** Section 2.1 - Outdated patterns + +**What Was Done:** + +- Emphasized auto-bundling over manual registration throughout +- Updated examples to use current best practices +- Added security note about automatic props sanitization +- Removed references to deprecated patterns + +**Impact:** + +- βœ… Users learn modern patterns first +- βœ… Less confusion about "old way" vs "new way" + +--- + +## ⚠️ What Remains Unresolved + +### 1. Information Architecture Still Problematic ❌ + +**Original Problem:** Section 1.1 - Unclear category hierarchy + +**Current State:** +The 11-category structure in `gatsby-node.js:31-44` **was not changed**: + +```javascript +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:** + +- ❌ Users still face 11 categories with unclear hierarchy +- ❌ "Outdated" still visible in navigation +- ❌ Contributor docs still mixed with user docs +- ❌ Testimonials still in technical docs + +**Evidence:** +From `01-problem-analysis.md` Section 1.1, all issues remain: + +- "Additional details" is still a vague bucket +- "Misc" still unclear +- "Guides" still too broad (18+ files) +- No beginner β†’ intermediate β†’ advanced progression + +--- + +### 2. Multiple Entry Points Still Confusing ❌ + +**Original Problem:** Section 1.2 - Four conflicting starting points + +**Current State After PR #1813:** + +1. **Root `README.md`** - Main project README (now better, but still project-level) +2. **`docs/README.md`** - New documentation hub (172 lines, comprehensive navigation) +3. **`docs/home.md`** - Still exists (29 lines, just links) - **Why?** +4. **`docs/getting-started.md`** - Enhanced (254 lines) but still tries to be everything +5. **`docs/quick-start/README.md`** - NEW (212 lines) - Great, but another entry point + +**Current User Experience:** + +A new user might land on: + +- GitHub repo β†’ sees root `README.md` β†’ links to `docs/` +- Docs site β†’ lands on... `docs/home.md`? `docs/README.md`? `getting-started.md`? +- Quick start β†’ `docs/quick-start/README.md` + +**Cross-References Create Circular Navigation:** + +From `docs/README.md:9-11`: + +```markdown +**β†’ [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`: + +```markdown +> **πŸ’‘ Looking for the fastest way to get started?** Try our **[15-Minute Quick Start Guide](./quick-start/README.md)** instead. +``` + +**Questions:** + +- If quick start is the fastest way, why show `getting-started.md` first? +- What is `docs/home.md` for? (Still unexplained) +- Should there be ONE canonical starting point? + +**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:** + +- ⚠️ Improved but not solved +- βœ… Better cross-referencing helps +- ❌ Still confusing for newcomers +- ❌ No single, clear "start here" page + +--- + +### 3. Concepts Still Not Explained Before Usage ❌ + +**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): + +````erb +- **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:** + +- Only shows 2 paths (beginner vs. experienced) +- No indication of time investment per section +- No prerequisites shown between docs +- All guides in category system still flat (no beginner/intermediate/advanced tags) + +**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 signposting +- ❌ Actual navigation still flat +- ❌ Beginners can still accidentally read advanced topics first +- ❌ No way to "filter" to just beginner content + +**What Would Fix This:** +Restructure categories in `gatsby-node.js`: + +```javascript +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) +]; +``` + +--- + +### 7. API Reference Still Mixed with Guides ⚠️ + +**Original Problem:** Section 3.2 - Reference vs. learning content not separated + +**Current State:** + +**Slight Improvement:** + +- `docs/api/` folder exists with 3 files +- `docs/README.md` has "API Reference" section + +**Still Mixed:** +From `docs/getting-started.md`: + +- Lines 86-120: API examples (how to use `react_component`) +- Lines 206-222: Documents `react_component_hash` (API reference) + +From `docs/guides/configuration.md` (316 lines): + +- Entire file is essentially API reference for config options +- But lives in "Guides" category + +**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: + +1. Moving content out of guides +2. Ensuring API docs are complete +3. Adding cross-references from guides to API +4. Risk of breaking user workflows + +PR #1813 improved existing docs but didn't reorganize this structure. + +**Impact:** + +- ⚠️ Better than before (API folder exists) +- ❌ Duplication still present +- ❌ No single source of truth for API +- ❌ Hard to maintain consistency + +**What Would Fix This:** + +**In Guides (learning):** + +```markdown +## 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):** + +```markdown +# 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] +``` + +--- + +### 8. Internal Docs Still in Navigation ❌ + +**Original Problem:** Section 1.3 - Contributor docs mixed with user docs + +**Current State:** +**Completely unchanged.** All these still in main navigation: + +1. **`contributor-info/` folder** - 5 files: + + - `linters.md` + - `coding-agents-guide.md` (newly created in PR #1813) + - `errors-with-hooks.md` + - `generator-testing.md` + - `releasing.md` + - `pull-requests.md` + +2. **Planning documents:** + + - `docs/planning/DOCUMENTATION_IMPROVEMENT_PLAN.md` (created in PR #1813) + - `docs/planning/DOCS_PR_SUMMARY.md` (created in PR #1813) + +3. **Root-level internal docs:** + - `docs/MONOREPO_MERGER_PLAN.md` + - `docs/DIRECTORY_LICENSING.md` + +**Why 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:** + +- ❌ Navigation still cluttered +- ❌ Unprofessional appearance (internal docs visible) +- ❌ Users might read contributor docs and get confused + +**What Would Fix This:** +In `sc-website/gatsby-node.js`, filter out internal directories: + +```javascript +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. + +--- + +### 9. Testimonials Still in Technical Docs ❌ + +**Original Problem:** Section 3.3 - Marketing content in docs + +**Current State:** +**Completely unchanged.** + +From `gatsby-node.js:41-42`: + +```javascript +"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:** + +- ❌ Unprofessional appearance +- ❌ Navigation clutter +- ❌ Inconsistent with industry standards + +**What Would Fix This:** + +1. Remove "Testimonials" category from `reactOnRailsDocsFoldersOrder` +2. Move testimonial content to shakacode.com marketing site +3. Add single link in introduction: "See who uses React on Rails β†’" + +--- + +### 10. "Outdated" Category Still Visible ❌ + +**Original Problem:** Section 1.4 - Deprecated docs in main nav + +**Current State:** +**Completely unchanged.** + +From `gatsby-node.js:43`: + +```javascript +"Outdated", // ← Still last category! +``` + +Still visible as the final category in navigation. + +**Why This Wasn't Fixed:** +Navigation restructuring not in scope. + +**Impact:** + +- ❌ Confusing for users +- ❌ Undermines trust in documentation +- ❌ May rank in search results + +**What Would Fix This:** + +1. Remove "Outdated" from `reactOnRailsDocsFoldersOrder` +2. Add regex filter to exclude outdated directory from build +3. Keep outdated docs in repo for reference but don't publish them +4. OR: Move to separate versioned docs (like `v15.shakacode.com/docs`) + +--- + +## πŸ“Š Summary Score Card + +| 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:** + +- βœ… **FIXED** - Problem fully resolved +- ⚠️ **IMPROVED/PARTIAL** - Problem partially addressed, work remains +- ❌ **UNRESOLVED** - Problem not addressed + +--- + +## 🎯 What PR #1813 Accomplished + +**Strengths:** + +1. βœ… **Tactical wins** - Fixed many immediate pain points +2. βœ… **Quality execution** - New content (quick start, troubleshooting) is well-written +3. βœ… **Technical debt** - Link checking, version consistency, formatting +4. βœ… **Modern patterns** - Auto-bundling emphasized, deprecated patterns removed +5. βœ… **User-focused** - Clear attention to user experience in new content + +**Type of Improvements:** + +- Content quality βœ… +- Consistency βœ… +- Accuracy βœ… +- Accessibility ⚠️ + +**What It Didn't Do:** + +- Structural changes ❌ +- Navigation redesign ❌ +- Information architecture ❌ +- New conceptual content ❌ + +--- + +## πŸš€ What Comes Next + +### Phase 1: Structural Foundations (High Priority) + +These require changes to **both** `react_on_rails` repo **and** `sc-website` repo: + +1. **Information Architecture Redesign** + + - Restructure 11 categories β†’ 6-7 logical groups + - Hide internal docs from main navigation + - Remove "Outdated" and "Testimonials" categories + - **Files to change:** `sc-website/gatsby-node.js:31-44` + +2. **Entry Point Consolidation** + + - Establish ONE canonical starting point + - Clarify purpose of each remaining entry doc + - Decision tree for "which guide to follow" + - **Files to change:** `docs/home.md`, `docs/README.md`, `docs/getting-started.md` + +3. **Progressive Disclosure System** + - Tag docs with difficulty level + - Restructure categories: Getting Started β†’ Core β†’ Advanced + - Filter navigation by user level + - **Files to change:** `gatsby-node.js` category order, frontmatter in docs + +### Phase 2: Content Additions (High Priority) + +These only require changes to `react_on_rails` repo: + +4. **Conceptual Guides** + + - "Understanding Server-Side Rendering" + - "How Bundling Works" + - "Component Registration Explained" + - "Props and RailsContext Deep Dive" + - **New files:** `docs/concepts/*.md` + +5. **Value Proposition Introduction** + + - "Why React on Rails?" + - Comparison with alternatives + - When to use / when not to use + - **New file:** `docs/introduction.md` + +6. **API Reference Consolidation** + - Complete, authoritative API docs + - Separate from learning guides + - Guides link to API reference + - **Refactor:** `docs/api/*.md` + remove duplication from guides + +### Phase 3: Polish and Enhance (Medium Priority) + +7. **Installation Decision Tree** + + - Clear signposting for different user journeys + - Consistent steps across all installation paths + +8. **Search and Metadata** + - Add frontmatter to all docs + - Improve SEO + - Better internal search + +--- + +## πŸ’‘ Recommendations + +### For Immediate Action: + +**Week 1-2: Information Architecture Redesign** + +- Highest impact for user experience +- Requires coordination between repos +- Foundation for all other improvements + +**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. + +### For Near-Term: + +**Week 3-4: Conceptual Guides** + +- Addresses critical "concepts not explained" problem +- Can be done independently of IA changes +- High value for beginners + +### For Medium-Term: + +**Month 2: Polish and Consistency** + +- Installation decision tree +- API reference consolidation +- Progressive disclosure tags + +--- + +## πŸ“ Conclusion + +**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:** + +1. Fix the floor plan (IA redesign) ← Phase 1 +2. Mark one clear front door (entry point consolidation) ← Phase 1 +3. Add room signage (progressive disclosure) ← Phase 1 +4. Then furnish the empty rooms (conceptual guides) ← Phase 2 diff --git a/docs/planning/docs-improvement/04-ia-redesign-plan.md b/docs/planning/docs-improvement/04-ia-redesign-plan.md new file mode 100644 index 0000000000..426d749019 --- /dev/null +++ b/docs/planning/docs-improvement/04-ia-redesign-plan.md @@ -0,0 +1,1365 @@ +# Information Architecture Redesign Plan (Section 1) + +**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 + +--- + +## Executive Summary + +This plan tackles ALL four Information Architecture problems identified in Section 1: + +- **1.1** Unclear Category Hierarchy (11 confusing categories) +- **1.2** Multiple Conflicting Entry Points (4 different starting points) +- **1.3** Internal Docs Visible (contributor/planning docs in user navigation) +- **1.4** "Outdated" Category Visible (deprecated docs exposed) + +**Core Strategy:** Redesign from user needs, not implementation details. Group by user journey stage (getting started β†’ learning β†’ building β†’ troubleshooting β†’ reference). + +--- + +## Problem Deep Dive + +### Current State: What's Broken + +**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:** + +1. ❌ Can't find what they need (too many places to look) +2. ❌ Don't know where to start (4 entry points) +3. ❌ See irrelevant content (internal docs, testimonials, outdated) +4. ❌ No progression (beginner and advanced mixed) +5. ❌ Catch-all categories lack meaning ("Additional details", "Misc") + +--- + +## Success Criteria + +**How do we know this redesign worked?** + +### Measurable Outcomes + +1. **Navigation clarity:** + + - βœ… User can find installation docs in < 10 seconds + - βœ… Clear difference between beginner and advanced topics + - βœ… One obvious starting point (not four) + +2. **Content organization:** + + - βœ… Every doc has clear category home + - βœ… No "catch-all" categories + - βœ… Internal docs hidden from main nav + +3. **Professional appearance:** + + - βœ… No "Outdated" category visible + - βœ… No testimonials in technical docs + - βœ… No planning documents in user nav + +4. **User feedback:** + - βœ… New users report easier onboarding + - βœ… Fewer "where do I find X?" questions + - βœ… Lower bounce rate on docs + +### Qualitative Goals + +- Navigation tells a story: "Start here β†’ Learn this β†’ Build that β†’ Get help" +- Categories have clear, single purposes +- User can predict where to find specific information + +--- + +## Proposed Solution + +### New Category Structure (8 Categories) + +**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:** + +- ❌ Contributor info β†’ Move to `/contributing/` or CONTRIBUTING.md +- ❌ Testimonials β†’ Move to marketing website +- ❌ Outdated β†’ Hide completely (keep in repo for reference) +- ❌ Planning docs β†’ Filter out (not user-facing) +- ❌ Internal docs (MONOREPO_MERGER_PLAN, etc.) β†’ Filter out + +--- + +### Detailed Category Mapping + +#### 1. πŸš€ Getting Started (6-8 docs) + +**Purpose:** Get users from zero to first working component ASAP. + +**Contents:** + +- **Introduction** (NEW - see Section 1.2 solution) + + - Why React on Rails? + - Comparison with alternatives + - When to use / when not to use + +- **Quick Start** (`quick-start/README.md`) + + - 15-minute setup + - First component + +- **Installation** (`guides/installation-into-an-existing-rails-app.md`) + + - Detailed installation for existing apps + +- **Tutorial** (`guides/tutorial.md`) + + - Comprehensive walkthrough + +- **Project Structure** (`additional-details/recommended-project-structure.md`) + - Where files go + - Naming conventions + +**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) +``` + +--- + +#### 2. πŸ“š Core Concepts (8-10 docs) + +**Purpose:** Explain fundamental concepts users need to understand. + +**Contents:** + +- **How React on Rails Works** (`guides/how-react-on-rails-works.md`) +- **Overview** (`guides/react-on-rails-overview.md`) +- **Client vs Server Rendering** (`guides/client-vs-server-rendering.md`) +- **Server-Side Rendering** (`guides/react-server-rendering.md`) +- **Component Registration** (`guides/render-functions-and-railscontext.md`) +- **Auto-Bundling** (`guides/auto-bundling-file-system-based-automated-bundle-generation.md`) +- **Webpack Integration** (`guides/webpack-configuration.md`) + +**NEW docs needed (from Problem 2.1):** + +- Understanding SSR (deep dive) +- How Bundling Works +- Props and RailsContext explained + +**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 +``` + +--- + +#### 3. πŸ”§ Building Features (10-12 docs) + +**Purpose:** Practical guides for building real features. + +**Contents:** + +**Common Patterns:** + +- **Hot Module Replacement** (`guides/hmr-and-hot-reloading-with-the-webpack-dev-server.md`) +- **Internationalization** (`guides/i18n.md`) +- **Testing Setup - RSpec** (`guides/rspec-configuration.md`) +- **Testing Setup - Minitest** (`guides/minitest-configuration.md`) + +**Advanced Techniques:** + +- **Streaming SSR** (`guides/streaming-server-rendering.md`) - ADVANCED +- **Conditional Rendering** (`guides/how-to-conditionally-server-render-based-on-device-type.md`) +- **Different Client/Server Files** (`guides/how-to-use-different-files-for-client-and-server-rendering.md`) + +**Integration Guides:** + +- **React Router** (`javascript/react-router.md`) +- **Redux** (`javascript/react-and-redux.md`) +- **React Helmet** (`javascript/react-helmet.md`) +- **Rails Integration Options** (`guides/rails-webpacker-react-integration-options.md`) + +**Tools & Workflow:** + +- **Code Splitting** (`javascript/code-splitting.md`) +- **Images** (`javascript/images.md`) +- **Foreman** (`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 +``` + +--- + +#### 4. πŸ“– API Reference (5-7 docs) + +**Purpose:** Quick lookup for syntax, options, parameters. + +**Contents:** + +- **View Helpers** (`api/view-helpers-api.md`) + + - react_component + - react_component_hash + - Options and parameters + +- **JavaScript API** (`api/javascript-api.md`) + + - ReactOnRails.register + - ReactOnRails.getStore + - etc. + +- **Redux Store API** (`api/redux-store-api.md`) + +- **Configuration API** (`guides/configuration.md`) + + - All config options reference + - ReactOnRails.configure do |config| options + +- **Generator Options** (`additional-details/generator-details.md`) + - react_on_rails:install flags + - What generator creates + +**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 +``` + +--- + +#### 5. 🚒 Deployment (8-10 docs) + +**Purpose:** Production deployment, troubleshooting, performance. + +**Contents:** + +**Production Setup:** + +- **Deployment Guide** (`guides/deployment.md`) +- **Heroku Deployment** (`deployment/heroku-deployment.md`) +- **Elastic Beanstalk** (`deployment/elastic-beanstalk.md`) +- **Capistrano** (`javascript/capistrano-deployment.md`) + +**Troubleshooting:** + +- **Troubleshooting Guide** (`troubleshooting/README.md`) - βœ… Already good from PR #1813 +- **Build Errors** (`javascript/troubleshooting-build-errors.md`) +- **Shakapacker Issues** (`javascript/troubleshooting-when-using-shakapacker.md`) +- **Webpacker Issues** (`javascript/troubleshooting-when-using-webpacker.md`) + +**Maintenance:** + +- **Updating Dependencies** (`additional-details/updating-dependencies.md`) +- **Performance Tips** (`misc/tips.md` - rename/move) + +**Rails-Specific:** + +- **Turbolinks** (`rails/turbolinks.md`) +- **Rails Engine Integration** (`rails/rails-engine-integration.md`) +- **Convert API-Only App** (`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 +``` + +--- + +#### 6. πŸ“ˆ Upgrading (5-7 docs) + +**Purpose:** Help users upgrade between React on Rails versions. + +**Contents:** + +- **Upgrading React on Rails** (`guides/upgrading-react-on-rails.md`) +- **Release Notes** (link to `release-notes/` folder) +- **Breaking Changes** (extract from CHANGELOG) +- **Upgrade Guides by Version:** + - v16.0.0 (`release-notes/16.0.0.md`) + - v15.0.0 (`release-notes/15.0.0.md`) +- **Pro Performance Upgrade Guide** (`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/ +``` + +--- + +#### 7. πŸ”„ Migrating (2-3 docs) + +**Purpose:** Help users migrate TO React on Rails from other tools. + +**Contents:** + +- **Migrating from react-rails** (`additional-details/migrating-from-react-rails.md`) +- **Migrating from AngularJS** (`javascript/angular-js-integration-migration.md`) + +**Could add (if valuable):** + +- Migrating from plain Rails views +- Migrating from Hotwire/Turbo +- Migrating from separate React SPA + +**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 +``` + +--- + +#### 8. πŸ’Ž React on Rails Pro (2-3 docs) + +**Purpose:** Showcase Pro features, link to Pro docs. + +**Contents:** + +- **React on Rails Pro Overview** (`react-on-rails-pro/react-on-rails-pro.md`) +- **Major Performance Breakthroughs** (`react-on-rails-pro/major-performance-breakthroughs-upgrade-guide.md`) +- **Link to Pro Documentation** (external) + +**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 +``` + +--- + +### Removed/Hidden Categories + +**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) + +--- + +## Solution: Entry Point Consolidation (Problem 1.2) + +### Current Situation: 4+ Entry Points + +**Problem:** Users land on different pages with no clear "start here": + +1. `docs/README.md` (173 lines) - Navigation hub +2. `docs/home.md` (29 lines) - Minimal landing +3. `docs/getting-started.md` (254 lines) - Installation + concepts + reference (too much) +4. `docs/quick-start/README.md` (212 lines) - 15-minute path +5. Root `README.md` - Project README (not docs landing page) + +### Proposed Solution: One Clear Entry Point + +**Create ONE landing page:** `docs/introduction.md` + +**This becomes the homepage** when users visit `/react-on-rails/docs/` + +**Structure:** + +```markdown +# 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:** + +1. **`docs/home.md`** β†’ DELETE (redundant) +2. **`docs/README.md`** β†’ DELETE or simplify to just TOC (not landing page) +3. **`docs/getting-started.md`** β†’ SPLIT: + - Installation content β†’ `docs/getting-started/installation.md` + - Concepts β†’ Move to Core Concepts category + - API examples β†’ Move to API Reference +4. **`docs/quick-start/README.md`** β†’ KEEP (but clearly positioned as one of three paths) +5. **Root `README.md`** β†’ KEEP (project README, not docs entry) + +**Result:** + +- βœ… ONE landing page: `introduction.md` +- βœ… THREE clear paths from there: Quick Start, Installation, Tutorial +- βœ… No circular references +- βœ… No confusion about "where do I start?" + +--- + +## Implementation Plan + +### Phase 1: Website Configuration (sc-website repo) + +**File:** `/home/ihab/ihab/work/shakacode/sc-website/gatsby-node.js` + +**Changes needed:** + +**1. Update category order (lines 31-44):** + +```javascript +// 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):** + +```javascript +// 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: + +- Option A: Filter in JavaScript after query +- Option B: Use regex to exclude paths +- Option C: Use `nin` (not in) operator + +**3. Update index page handling (around line 196):** + +```javascript +// Ensure introduction.md becomes homepage +const indexPages = ['introduction']; +``` + +**Testing checklist:** + +- [ ] Run `gatsby develop` locally in sc-website +- [ ] Verify new categories appear +- [ ] Verify internal docs hidden +- [ ] Verify introduction.md becomes homepage +- [ ] Check all links work +- [ ] Test mobile navigation + +--- + +### Phase 2: Content Reorganization (react_on_rails repo) + +**Strategy:** Move files to match new category structure + +**Approach options:** + +**Option A: Create new folders matching categories** + +```bash +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** + +- Keep current file locations +- Categories map to folders via label transformation +- Requires folder renames to match categories + +**Recommendation: Option A** (new folders) + +- Clearer structure +- Easier to understand +- Better for future maintenance +- Git history preserved with `git mv` + +**File moves needed:** + +Create script: `scripts/reorganize-docs.sh` + +```bash +#!/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:** + +- [ ] Run reorganization script +- [ ] Verify all files moved correctly +- [ ] Check for broken internal links +- [ ] Update any absolute paths in docs +- [ ] Test locally that categories work +- [ ] Git commit with clear message + +--- + +### Phase 3: Content Updates (react_on_rails repo) + +**Create new files:** + +**1. `docs/introduction.md`** + +- Homepage for docs +- Explains what React on Rails is +- Why use it vs alternatives +- Links to three paths (Quick Start, Installation, Tutorial) +- Philosophy section + +**2. Split `docs/getting-started.md`:** + +- Move installation β†’ `docs/getting-started/installation.md` +- Move concepts β†’ Core Concepts category +- Move API examples β†’ API Reference +- DELETE original after content extracted + +**3. Update `docs/README.md`:** +Option A: Delete entirely (introduction.md is new homepage) +Option B: Keep as simple TOC without learning paths + +**4. Delete `docs/home.md`:** + +- Redundant with introduction.md + +**5. Update cross-references:** + +- Search all docs for links to moved files +- Update relative paths +- Automated script: + +```bash +#!/bin/bash +# Update internal links after reorganization + +# Find all .md files +find docs -name "*.md" -type f | while read file; do + # Replace old paths with new paths + sed -i 's|guides/installation-into-an-existing-rails-app.md|getting-started/installation.md|g' "$file" + sed -i 's|guides/tutorial.md|getting-started/tutorial.md|g' "$file" + sed -i 's|guides/how-react-on-rails-works.md|core-concepts/how-it-works.md|g' "$file" + # ... etc for all moved files +done +``` + +**Testing checklist:** + +- [ ] All new files created +- [ ] Old files deleted or split +- [ ] All internal links updated +- [ ] Run markdown link checker +- [ ] Manual spot-checks of navigation +- [ ] Test on local gatsby build + +--- + +### Phase 4: Contributor Docs (react_on_rails repo) + +**Move contributor content:** + +**Update `CONTRIBUTING.md` to include:** + +- Content from `docs/contributor-info/linters.md` +- Content from `docs/contributor-info/coding-agents-guide.md` +- Content from `docs/contributor-info/generator-testing.md` +- Content from `docs/contributor-info/releasing.md` +- Content from `docs/contributor-info/pull-requests.md` +- Content from `docs/misc/style.md` + +**OR create `/contributing/` documentation site** (separate from user docs) + +**Delete after moving:** + +```bash +rm -rf docs/contributor-info +rm docs/misc/style.md +``` + +**Move to root:** + +```bash +git mv docs/misc/code_of_conduct.md CODE_OF_CONDUCT.md +``` + +**Testing checklist:** + +- [ ] CONTRIBUTING.md comprehensive +- [ ] Contributor info not in user docs +- [ ] CODE_OF_CONDUCT.md at root +- [ ] Links to CONTRIBUTING.md work + +--- + +### Phase 5: Testimonials & Marketing (both repos) + +**In react_on_rails repo:** + +```bash +# Remove testimonials from docs +rm -rf docs/testimonials +``` + +**In sc-website repo:** + +- Create `/testimonials/` or `/case-studies/` page +- Import testimonial content +- Add links from introduction.md: "See who uses React on Rails β†’" + +**Testing checklist:** + +- [ ] Testimonials not in docs navigation +- [ ] Testimonials page exists on marketing site +- [ ] Link from docs to testimonials works + +--- + +### Phase 6: Outdated Content (react_on_rails repo) + +**Options:** + +**Option A: Hide from build, keep in repo** + +```bash +# Keep files but exclude from gatsby build +# Already done in Phase 1 (gatsby-node.js filter) +``` + +**Option B: Move to separate branch** + +```bash +git checkout -b archive/outdated-docs +git mv docs/outdated / +git commit -m "Archive outdated docs" +git checkout master +rm -rf docs/outdated +``` + +**Option C: Delete entirely** + +```bash +rm -rf docs/outdated +``` + +**Recommendation: Option A** (keep in repo, exclude from build) + +- Preserves history +- Still accessible if needed +- Not visible to users + +**Testing checklist:** + +- [ ] Outdated category not in navigation +- [ ] Files still in repo (if Option A) +- [ ] No broken links to outdated docs + +--- + +## Files to Modify Summary + +### In `sc-website` repo: + +1. **`gatsby-node.js`** + + - Update `reactOnRailsDocsFoldersOrder` (lines 31-44) + - Add filter to exclude internal docs (around line 151) + - Update index page handling (around line 196) + +2. **Test locally:** + - Run gatsby develop + - Verify navigation + - Check links + +### In `react_on_rails` repo: + +**New files:** + +1. `docs/introduction.md` (homepage) +2. `scripts/reorganize-docs.sh` (file moving script) +3. `scripts/update-links.sh` (link updating script) + +**Modified files:** + +1. Update `CONTRIBUTING.md` (add contributor content) +2. Update internal link references (all .md files) + +**Deleted files:** + +1. `docs/home.md` +2. `docs/README.md` (or drastically simplified) +3. `docs/getting-started.md` (content extracted) +4. `docs/contributor-info/*` (moved to CONTRIBUTING.md) +5. `docs/testimonials/*` (moved to marketing site) +6. `docs/misc/style.md` (moved to CONTRIBUTING.md) + +**Moved files:** + +- ~80 files moved to new structure (see Phase 2 script) + +--- + +## Timeline Estimate + +**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) + +--- + +## Rollback Plan + +**If something goes wrong:** + +### Quick Rollback (Website Config) + +**In `sc-website` repo:** + +```bash +git revert +npm run build +npm run deploy +``` + +**Result:** Old category structure restored immediately. + +### Full Rollback (Content Reorganization) + +**In `react_on_rails` repo:** + +```bash +# Revert file moves +git revert + +# Or if not committed yet: +git reset --hard HEAD +``` + +**Result:** Files back in original locations. + +### Partial Rollback + +If only some categories are problematic: + +1. Keep working categories +2. Revert problematic ones +3. Fix issues +4. Re-deploy + +**Risk mitigation:** + +- βœ… Test on staging first +- βœ… Deploy website changes separately from content changes +- βœ… Keep PRs focused (one phase per PR) +- βœ… Document each change clearly + +--- + +## Testing Strategy + +### Pre-Deployment Testing + +**1. Local Gatsby Build (sc-website):** + +```bash +cd sc-website +npm install +gatsby develop +# Visit http://localhost:8000/react-on-rails/docs/ +``` + +**Check:** + +- [ ] New categories appear correctly +- [ ] Internal docs hidden +- [ ] introduction.md is homepage +- [ ] All links work +- [ ] Mobile navigation works +- [ ] Search works (if applicable) + +**2. Local React on Rails Testing:** + +```bash +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:** + +- [ ] All files in correct locations +- [ ] No broken internal links +- [ ] No 404s on moved files + +**3. User Journey Testing:** + +**Test Scenario 1: New User** + +- Land on docs homepage +- Can find Quick Start in < 10 seconds +- Complete Quick Start without confusion +- Can navigate to Core Concepts + +**Test Scenario 2: Experienced User Looking for API** + +- Land on docs homepage +- Can find API Reference in < 5 seconds +- Can look up react_component options +- Can return to previous page + +**Test Scenario 3: User with Problem** + +- Land on docs homepage +- Can find Troubleshooting in < 10 seconds +- Can diagnose issue type +- Can find solution + +**4. Cross-Browser Testing:** + +- [ ] Chrome +- [ ] Firefox +- [ ] Safari +- [ ] Mobile Safari +- [ ] Mobile Chrome + +--- + +### Post-Deployment Verification + +**1. Production Checks:** + +```bash +# Visit actual site +open https://www.shakacode.com/react-on-rails/docs/ + +# Check Google Search Console (after a few days) +# - Are old URLs redirecting? +# - Are new URLs indexed? +``` + +**2. Monitor Issues:** + +- [ ] Watch GitHub issues for "can't find X" questions +- [ ] Monitor Slack for navigation confusion +- [ ] Track analytics (bounce rate, time on page) + +**3. Gather Feedback:** + +- [ ] Ask beta users to test +- [ ] Post in community: "We reorganized docs, feedback?" +- [ ] Monitor social media mentions + +--- + +## Success Metrics (After 2-4 Weeks) + +**Quantitative:** + +1. **Bounce rate** on docs pages decreases by 10-20% +2. **Time to find specific info** (via user testing) decreases by 30% +3. **"Where is X?" questions** in issues/Slack decrease by 40% +4. **Page views** on key pages (Quick Start, Installation) increase by 20% + +**Qualitative:** + +1. βœ… Positive feedback from community +2. βœ… Fewer confused new users +3. βœ… More self-service, less support needed +4. βœ… Better reviews/mentions of docs quality + +--- + +## Dependencies & Coordination + +### Team Coordination Needed + +**1. Justin (Maintainer):** + +- Review IA redesign plan +- Approve category structure +- Review content changes +- Deploy website changes + +**2. Bob (Mentor):** + +- Review technical approach +- Test navigation changes +- Provide feedback on content + +**3. Ihab (You):** + +- Execute reorganization +- Write introduction.md +- Update links +- Test thoroughly + +### External Dependencies + +**1. Gatsby Build System:** + +- Must understand how gatsby-node.js creates pages +- Need access to sc-website repo +- Need ability to test locally + +**2. Git History:** + +- Use `git mv` to preserve history +- Commit in logical chunks +- Write clear commit messages + +**3. CI/CD Pipeline:** + +- Ensure link checker still works +- RuboCop/Prettier formatting maintained +- No breaking changes to build + +--- + +## Risk Assessment + +| 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 | + +--- + +## Open Questions + +**To discuss with team:** + +1. **Should we keep `docs/README.md` or delete it?** + + - Option A: Delete (introduction.md is new homepage) + - Option B: Keep as simple TOC + - **Recommendation:** Delete (simplify entry points) + +2. **What to do with `docs/misc/doctrine.md`?** + + - Option A: Integrate into introduction.md (philosophy section) + - Option B: Separate "Philosophy" page + - **Recommendation:** Integrate (fewer top-level pages) + +3. **Should contributor docs be in CONTRIBUTING.md or separate site?** + + - Option A: All in CONTRIBUTING.md (simple) + - Option B: Separate `/contributing/` docs site (more discoverable) + - **Recommendation:** CONTRIBUTING.md for now (simpler) + +4. **How to handle testimonials on marketing site?** + + - Option A: New /testimonials page + - Option B: Integrate into /case-studies + - Option C: Scatter across site (homepage, about, etc.) + - **Recommendation:** Get marketing team input + +5. **Should we add version switcher?** + + - For v15 vs v16 docs + - Similar to Next.js version switcher + - **Recommendation:** Defer to later phase (nice-to-have) + +6. **Redirect old URLs to new ones?** + - Set up 301 redirects for moved pages + - Or let 404s naturally resolve over time + - **Recommendation:** Yes, set up redirects (better UX) + +--- + +## Next Steps + +**Before starting implementation:** + +1. **Review this plan with Justin and Bob** + + - Get feedback on category structure + - Confirm approach is sound + - Resolve open questions + +2. **Prioritize phases** + + - Must-do: Phases 1-3 (core IA changes) + - Nice-to-have: Phases 4-6 (cleanup) + +3. **Set up staging environment** + + - Fork sc-website repo + - Test locally + - Deploy to staging if available + +4. **Create tracking issue** + - GitHub issue linking to this plan + - Checklist of phases + - Track progress + +**After plan approved:** + +1. **Start with Phase 1** (website config) + + - Small, testable change + - See if approach works + - Learn the system + +2. **Get feedback early** + + - Show category structure working + - Adjust if needed + - Build confidence + +3. **Move to Phase 2** (file moves) + + - Bigger change but mechanical + - Run script, test, commit + +4. **Complete remaining phases** + - One phase per PR + - Test thoroughly + - Iterate based on feedback + +--- + +## Conclusion + +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:** + +- Users can find what they need quickly +- Clear progression from beginner to advanced +- Professional appearance (no clutter) +- One obvious starting point +- Better first impression + +**This is foundational work** that makes all future documentation improvements easier. Once the structure is right, we can: + +- Add conceptual guides (Problem 2.1) +- Improve installation flow (Problem 2.2) +- Add progressive disclosure (Problem 3.1) +- Consolidate API reference (Problem 3.2) + +**Estimated effort:** 22-28 hours (~3-4 days) +**Risk:** Medium (testing and rollback plan mitigate) +**Impact:** πŸ”₯πŸ”₯πŸ”₯ Critical - fixes foundation for all other improvements diff --git a/docs/planning/docs-improvement/GITHUB_ISSUE_DRAFT.md b/docs/planning/docs-improvement/GITHUB_ISSUE_DRAFT.md new file mode 100644 index 0000000000..4fd2310a3a --- /dev/null +++ b/docs/planning/docs-improvement/GITHUB_ISSUE_DRAFT.md @@ -0,0 +1,213 @@ +# GitHub Issue Draft: Documentation IA Redesign + +**Copy/paste this into a new GitHub issue** + +--- + +## Title + +[RFC] Documentation Information Architecture Redesign + +--- + +## Labels + +- `documentation` +- `enhancement` +- `discussion` + +--- + +## Issue Body + +--- + +## Problem + +React on Rails documentation has **unclear navigation structure** that makes it difficult for users to find information and understand the learning path. + +### Current Issues + +**1. 11 Confusing Categories** + +Our documentation is organized into 11 categories with unclear purposes: + +- "Guides" (21 files) - everything from installation to advanced SSR +- "Additional details" - catch-all with unrelated content +- "Misc" - another catch-all +- "Javascript" - build tools mixed with React patterns +- "Rails" - integration topics +- "Contributor info" - **internal docs in user navigation** ❌ +- "Testimonials" - **marketing content in technical docs** ❌ +- "Outdated" - **deprecated docs visible to users** ❌ + +**User impact:** Can't find information quickly, no clear beginnerβ†’advanced progression. + +**2. Homepage File Conflict** + +Two files in the repo map to the same docs homepage URL: + +- `docs/home.md` β†’ `/react-on-rails/docs/` +- `docs/README.md` β†’ `/react-on-rails/docs/` + +Only one can render (non-deterministic which "wins"). This creates confusion about which file is the actual homepage. + +**Note:** _Website build appears outdated (last deployed Sept 21, PR #1813 merged Sept 23). We should verify the actual user experience after the website rebuilds with latest docs from master branch. The entry points problem may need reassessment once the site is updated._ + +**3. No Clear User Journey** + +Documentation is organized by **implementation details** (Javascript, Rails, API) rather than **user needs** (Getting Started, Building Features, Troubleshooting). + +Beginners see advanced topics (streaming SSR, conditional rendering) mixed with basics (installation, first component). + +--- + +## Proposed Solution + +### New Category Structure (7 Categories) + +Reorganize around **user journey stages**: + +``` +1. πŸš€ Getting Started β†’ Onboarding, first component (6-8 docs) +2. πŸ“š Core Concepts β†’ SSR, bundling, how it works (8-10 docs) +3. πŸ”§ Building Features β†’ Common patterns, integrations (10-12 docs) +4. πŸ“– API Reference β†’ View helpers, config, JS API (5-7 docs) +5. 🚒 Deployment β†’ Production, troubleshooting (8-10 docs) +6. πŸ”„ Migration β†’ Upgrading, migrating from others (5-7 docs) +7. πŸ’Ž React on Rails Pro β†’ Pro features (2-3 docs) +``` + +**Removed from user navigation:** + +- Contributor docs β†’ moved to `CONTRIBUTING.md` +- Testimonials β†’ moved to marketing website +- Outdated docs β†’ hidden from navigation +- Internal docs β†’ filtered from build + +### Single Entry Point + +Create **one clear homepage**: `docs/introduction.md` + +**Contains:** + +- What is React on Rails? (value proposition) +- Why React on Rails vs. alternatives? (comparison) +- When to use / when not to use (decision guide) +- **Three clear paths:** + - πŸš€ Quick Start (15 minutes) + - πŸ“¦ Installation Guide (existing app) + - πŸ“š Full Tutorial (comprehensive) + +**Resolve homepage conflict:** + +- Decide whether `home.md` or `README.md` should be homepage, or replace both with `introduction.md` +- Update gatsby-node.js to map one file to `/docs/` +- Delete or repurpose the redundant file + +--- + +## Implementation Overview + +### Phase 1: Website Configuration (`sc-website` repo) + +Update `gatsby-node.js`: + +- Change category order from 11 to 7 categories +- Add filter to exclude internal docs +- Set `introduction.md` as homepage + +**Estimated:** 2-3 hours + +### Phase 2: Content Reorganization (`react_on_rails` repo) + +Create new folder structure: + +``` +docs/ +β”œβ”€β”€ introduction.md # NEW HOMEPAGE +β”œβ”€β”€ getting-started/ +β”‚ β”œβ”€β”€ quick-start.md +β”‚ β”œβ”€β”€ installation.md +β”‚ └── tutorial.md +β”œβ”€β”€ core-concepts/ +β”œβ”€β”€ building/ +β”œβ”€β”€ api-reference/ +β”œβ”€β”€ deployment/ +β”œβ”€β”€ migration/ +└── pro/ +``` + +Move ~80 files to new locations with `git mv` (preserves history). + +**Estimated:** 4-5 hours + +### Phase 3: Content Updates + +- Create `introduction.md` homepage +- Split `getting-started.md` into appropriate sections +- Update all internal links +- Delete redundant files + +**Estimated:** 6-8 hours + +### Phases 4-6: Cleanup + +- Move contributor docs to `CONTRIBUTING.md` +- Coordinate testimonial move to marketing site +- Hide outdated content + +**Estimated:** 5-6 hours + +**Total estimated time:** 22-28 hours (~3-4 days) + +--- + +## Benefits + +### For Users + +βœ… **Find information in <10 seconds** - Clear category names +βœ… **Understand learning path** - Beginnerβ†’Advanced progression +βœ… **One obvious starting point** - No more confusion +βœ… **Professional appearance** - No internal docs, no "Outdated" category + +### For Maintainers + +βœ… **Easier to add new content** - Clear category homes +βœ… **Better organization** - No more catch-all categories +βœ… **Reduced support burden** - Users find answers faster + +--- + +## Questions for Review + +1. **Website rebuild**: Should we trigger a website rebuild first to see current state with PR #1813 changes before planning further? + +2. **Category structure**: Do these 7 categories make sense for user journeys? + +3. **Entry point strategy**: Is one `introduction.md` homepage the right approach? + +4. **Contributor docs**: Should they go in `CONTRIBUTING.md` or separate `/contributing/` site? + +5. **Testimonials**: Best place on marketing site? + +6. **Implementation order**: Should we do website config first (Phase 1) to test, or all at once? + +7. **Rollback plan**: Satisfied with git revert strategy if issues arise? + +--- + +## Next Steps + +Once approved: + +1. Create tracking checklist issue or project board +2. Start with Phase 1 (website config) as proof-of-concept +3. Get early feedback on category rendering +4. Proceed with content reorganization +5. Iterate based on team and user feedback + +--- + +**Note:** This addresses **Section 1 (Information Architecture)** problems. After completion, we can tackle **Section 2 (Beginner Onboarding)** issues like missing conceptual guides. diff --git a/docs/planning/docs-improvement/ia-redesign-live.md b/docs/planning/docs-improvement/ia-redesign-live.md new file mode 100644 index 0000000000..bc4e2392e9 --- /dev/null +++ b/docs/planning/docs-improvement/ia-redesign-live.md @@ -0,0 +1,414 @@ +# IA Redesign - Live Implementation Tracker + +**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 + +--- + +## Implementation Approach + +We're breaking Phase 2 (File Reorganization) into 8 reviewable steps, pausing between each for review before proceeding. + +### Why Step-by-Step? + +- This is critical infrastructure - can't rush it +- Each step is reviewable and reversible +- Learn from each step before proceeding +- Catch issues early before they compound + +--- + +## Step-by-Step Plan + +### βœ… Step 0: Setup & Baseline + +- [x] Create feature branch `feature/docs-ia-redesign` +- [x] Commit all planning docs (clean baseline for diffs) +- [x] Create this live tracker +- [ ] Create empty folder structure +- [ ] Review structure before moving files + +**Status:** In Progress +**Started:** October 2, 2025 + +--- + +### ⏸️ Step 1: Move Getting Started Files (~6-8 files) + +- [ ] Move files using `git mv` +- [ ] Verify git history preserved +- [ ] Check for any immediate issues +- [ ] Wait for review before next step + +**Rationale:** Small, clear category to validate our approach. + +**Status:** Pending +**Files to move:** TBD (from plan mapping) + +--- + +### ⏸️ Step 2: Move Core Concepts Files (~8-10 files) + +- [ ] Move files using `git mv` +- [ ] Check for link breakage patterns +- [ ] Wait for review + +**Status:** Pending + +--- + +### ⏸️ Step 3: Move Building Features Files (~10-12 files) + +- [ ] Move files using `git mv` +- [ ] Larger category - good stress test +- [ ] Wait for review + +**Status:** Pending + +--- + +### ⏸️ Step 4: Move API Reference Files (~5-7 files) + +- [ ] Move files using `git mv` +- [ ] Straightforward technical docs +- [ ] Wait for review + +**Status:** Pending + +--- + +### ⏸️ Step 5: Move Deployment Files (~8-10 files) + +- [ ] Move files using `git mv` +- [ ] Includes troubleshooting content +- [ ] Wait for review + +**Status:** Pending + +--- + +### ⏸️ Step 6: Move Migration & Upgrading Files (~5-7 files) + +- [ ] Move files using `git mv` +- [ ] Version-specific content +- [ ] Wait for review + +**Status:** Pending + +--- + +### ⏸️ Step 7: Move Pro Files (~2-3 files) + +- [ ] Move files using `git mv` +- [ ] Small, contained category +- [ ] Wait for review + +**Status:** Pending + +--- + +### ⏸️ Step 8: Handle Special Files + +- [ ] Create new `introduction.md` homepage +- [ ] Delete/archive `home.md` and `README.md` +- [ ] Final review before moving to Phase 1 + +**Status:** Pending + +--- + +## Decisions & Adaptations + +This section tracks any deviations from the original plan and why we made them. + +### Decision Log + +#### Decision 1: Split Migration & Upgrading into Two Categories (Oct 2, 2025) + +**Original plan:** Category 6 called "Migration & Upgrading" in one folder `migration/` + +**Decision:** Split into TWO separate categories: + +- Category 6: πŸ“ˆ **Upgrading** (`upgrading/`) - Version upgrades, release notes +- Category 7: πŸ”„ **Migrating** (`migrating/`) - From other tools (react-rails, angular, etc.) + +**Rationale:** + +- Research showed popular frameworks use separate "Upgrading" and "Migrating" sections +- Clear distinction: upgrading = staying with RoR between versions; migrating = coming FROM other tools +- Both are important enough to warrant separate categories +- Users have different intents: "I need to upgrade" vs "I'm switching from react-rails" +- Only adds 1 category (8 total vs original 7) - still way better than current 11 + +**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 guides +- `migrating/`: from-react-rails.md, from-angular.md + +--- + +#### Decision 2: Keep Descriptive Long Filenames (Oct 2, 2025) + +**Question:** Should we rename `installation-into-an-existing-rails-app.md` to just `installation.md`? + +**Decision:** Keep the original long descriptive filename. + +**Rationale:** + +- The distinction between "existing Rails app" vs "new Rails app" is meaningful +- `tutorial.md` covers installation for NEW apps (with `rails new`) +- `installation-into-an-existing-rails-app.md` covers EXISTING apps (already have code) +- Shortening to `installation.md` creates ambiguity - users won't know which scenario it covers +- Descriptive filenames help users find the right doc for their situation + +**Pattern:** Prefer descriptive filenames over short ones when there's meaningful distinction. + +--- + +#### Decision 3: Move configuration.md to API Reference (Oct 2, 2025) + +**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 options +- Same format as `view-helpers-api.md` and `javascript-api.md` (method/parameter lists) +- Users look it up when they need a specific setting (reference usage pattern) +- Not teaching a concept - documenting an interface +- Core Concepts = understanding how things work; API Reference = lookup tables for methods/configs + +**Pattern:** Reference lists of options/methods/parameters belong in API Reference, not Core Concepts. + +--- + +#### Decision 4: Rethink Deployment Category - Remove Non-Deployment Files (Oct 3, 2025) + +**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): + +1. `updating-dependencies.md` β†’ **misc/updating-dependencies.md** (temporary holding) +2. `turbolinks.md` β†’ **building-features/turbolinks.md** (feature integration) +3. `rails-engine-integration.md` β†’ **advanced-topics/rails-engine-integration.md** (temporary holding) +4. `convert-rails-5-api-only-app.md` β†’ **migrating/convert-rails-5-api-only-app.md** (prerequisite migration) +5. `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):** + +- Production deployment guides (4 files: deployment.md, capistrano, heroku, elastic-beanstalk) +- Troubleshooting production/CI issues (3 files) + +**Rationale:** + +- Don't force-fit files to match the plan if they don't belong +- Follow industry standards: categorize by user intent, not by technology +- Protect important categories from bloat +- Gather orphaned files in temporary categories for later review +- Deployment should be about getting to production and operating in production + +**Pattern:** Categorize by WHEN and WHY users need the info, not by what technology it involves. + +--- + +#### Decision 5: No "Rails" Category Needed (Oct 3, 2025) + +**Question:** Should we create a "Rails" category for Rails-specific files? + +**Decision:** NO - do not create a "Rails" category. + +**Rationale:** + +- React on Rails IS a Rails integration - everything is Rails-related +- A "Rails" category would become a dumping ground like the old "Additional details" +- Better to categorize by user intent (what are they trying to do?) not by technology +- Industry pattern: Stimulus, Turbo, Inertia.js don't have "Rails" categories +- Files from old `rails/` folder distributed to appropriate categories by intent + +**Pattern:** Intent-based categorization (user journey) beats technology-based categorization. + +--- + +## Issues & Blockers + +### Issue 1: Content Overlap in Getting Started (Oct 2, 2025) + +**Problem:** Three files overlap significantly in covering installation: + +1. **quick-start.md** (212 lines) + - 15-minute setup + - Assumes existing Rails app (or just run `rails new`) + - Steps: install gem β†’ run generator β†’ hello world +2. **installation-into-an-existing-rails-app.md** (67 lines) + - Detailed installation for existing apps + - Very similar steps to quick-start +3. **tutorial.md** (389 lines) + - Comprehensive walkthrough with `rails new` + - Includes installation + features + deployment + +**Issue:** 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: + +- Merge quick-start and installation docs +- Delete one and improve the other +- Clarify when to use each with better headers/descriptions + +_This is a content problem, not a structure problem. Keep moving files for now._ + +--- + +## Testing Notes + +### Local Testing Strategy + +- Use `gatsby develop` in sc-website repo pointing to this branch +- Verify categories render correctly +- Check navigation flow +- Test internal links + +_Test results will be logged here as we go_ + +--- + +## Completion Summary + +**βœ… ALL STEPS COMPLETE (Steps 1-8):** + +- Step 1: Getting Started (4 files) +- Step 2: Core Concepts (7 files) + API Reference (1 file) +- Step 3: Building Features (14 files) +- Step 4: API Reference (4 files) +- Step 5: Deployment (9 files, then corrected to 7) +- Step 6: Upgrading (4 files, then moved 1 to pro) +- Step 7: Migrating (2 files) +- Step 8: Pro (1 file) + +**βœ… ORPHANED FILES REORGANIZED (12 files):** +After Steps 1-8, found 12 files not in original plan. Investigated and reorganized: + +- 7 moved to existing categories +- 4 moved to outdated/ +- 1 merged and deleted + +**Total files moved:** ~50+ files across all steps + +**Next Actions:** Update website config, update internal links, create introduction.md + +--- + +## Reference: Final Folder Structure + +``` +docs/ +β”œβ”€β”€ introduction.md # TODO: Create in next phase +β”œβ”€β”€ getting-started/ (4 files) +β”‚ β”œβ”€β”€ quick-start.md +β”‚ β”œβ”€β”€ installation-into-an-existing-rails-app.md +β”‚ β”œβ”€β”€ tutorial.md +β”‚ └── project-structure.md +β”œβ”€β”€ core-concepts/ (8 files) +β”‚ β”œβ”€β”€ how-react-on-rails-works.md +β”‚ β”œβ”€β”€ react-on-rails-overview.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 +β”‚ β”œβ”€β”€ 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/ (2 files - KEEPING as category) + β”œβ”€β”€ rails-engine-integration.md # Step 5 correction: from deployment + └── manual-installation-overview.md # Orphaned: manual setup guide +``` + +**Final Decisions:** + +- `misc/` and `advanced-topics/` are now PERMANENT categories (not temporary) +- All orphaned files found homes +- Old folders (guides/, javascript/, additional-details/, etc.) are now EMPTY + +See `04-ia-redesign-plan.md` for original plan (NOTE: this live doc is source of truth after Steps 1-8 + orphaned files). diff --git a/docs/react-on-rails-pro/major-performance-breakthroughs-upgrade-guide.md b/docs/pro/major-performance-breakthroughs-upgrade-guide.md similarity index 100% rename from docs/react-on-rails-pro/major-performance-breakthroughs-upgrade-guide.md rename to docs/pro/major-performance-breakthroughs-upgrade-guide.md diff --git a/docs/react-on-rails-pro/react-on-rails-pro.md b/docs/pro/react-on-rails-pro.md similarity index 100% rename from docs/react-on-rails-pro/react-on-rails-pro.md rename to docs/pro/react-on-rails-pro.md diff --git a/docs/release-notes/15.0.0.md b/docs/upgrading/release-notes/15.0.0.md similarity index 100% rename from docs/release-notes/15.0.0.md rename to docs/upgrading/release-notes/15.0.0.md diff --git a/docs/release-notes/16.0.0.md b/docs/upgrading/release-notes/16.0.0.md similarity index 97% rename from docs/release-notes/16.0.0.md rename to docs/upgrading/release-notes/16.0.0.md index f48aefd488..cb5e0086e5 100644 --- a/docs/release-notes/16.0.0.md +++ b/docs/upgrading/release-notes/16.0.0.md @@ -34,7 +34,7 @@ This optimization is particularly impactful for: _Performance improvement visualization:_ -![Performance comparison showing early hydration improvement](../assets/early-hydration-performance-comparison.jpg) +![Performance comparison showing early hydration improvement](../../assets/early-hydration-performance-comparison.jpg) _The image above demonstrates the dramatic performance improvement:_ @@ -81,7 +81,7 @@ _The image above demonstrates the dramatic performance improvement:_ // Code expecting all components to be hydrated ``` - - If you call it in a `turbolinks:load` listener to work around the issue documented in [Turbolinks](../rails/turbolinks.md#async-script-loading), the listener can be safely removed. + - If you call it in a `turbolinks:load` listener to work around the issue documented in [Turbolinks](../../building-features/turbolinks.md#async-script-loading), the listener can be safely removed. ### Script Loading Strategy Migration diff --git a/docs/guides/upgrading-react-on-rails.md b/docs/upgrading/upgrading-react-on-rails.md similarity index 99% rename from docs/guides/upgrading-react-on-rails.md rename to docs/upgrading/upgrading-react-on-rails.md index 888b428d13..5a04d10a41 100644 --- a/docs/guides/upgrading-react-on-rails.md +++ b/docs/upgrading/upgrading-react-on-rails.md @@ -93,7 +93,7 @@ rails generate react_on_rails:install 2. Verify all ProvidePlugin modules exist 3. Check webpack alias configuration -For troubleshooting build errors, see the [build errors guide](../javascript/troubleshooting-build-errors.md). +For troubleshooting build errors, see the [build errors guide](../deployment/troubleshooting-build-errors.md). ### Enhanced Features in v16 @@ -141,7 +141,7 @@ If you still need that feature, please file an issue. In order to solve the issues regarding React Hooks compatibility, the number of parameters for functions is used to determine if you have a Render-Function that will get invoked to return a React component, or you are registering a React component defined by a function. -Please see [Render-Functions and the Rails Context](./render-functions-and-railscontext.md) for +Please see [Render-Functions and the Rails Context](../core-concepts/render-functions-and-railscontext.md) for more information on what a Render-Function is. ##### Update required for registered functions taking exactly 2 params.