Add more guidance for people who are creating their first Rails app #47620

bradgessler · 2023-03-09T20:51:48Z

Motivation / Background

I tweeted at https://twitter.com/bradgessler/status/1630655637096108032 that with relatively low effort, Rails could be more welcoming to new folks if we can give them a little more guidance. I expanded on that thought a bit with the post at https://fly.io/ruby-dispatch/little-gestures-of-confidence/.

Both of those links should be sufficient to describe the motivation and background.

Detail

Adds a blurb to rails new that tells people to boot the server or enter rails help

$ rails new hello-rails
# stuff happens...
Appending: pin "@hotwired/stimulus-loading", to: "stimulus-loading.js", preload: true
      append  config/importmap.rb
Pin all controllers
Appending: pin_all_from "app/javascript/controllers", under: "controllers"
      append  config/importmap.rb

Rails project created and dependencies installed.

Now switch to the directory where the Rails app was created:

  $ cd hello-rails

Then boot the development server:

  $ ./bin/rails server

You can always get help by running:

  $ ./bin/rails help

Adds a blurb to the rails welcome screen that tells people where they can find their code:

Additional information

Checklist

Before submitting the PR make sure the following are checked:

This Pull Request is related to one change. Changes that are unrelated should be opened in separate PRs.
Commit message has a detailed description of what changed and why. If this PR fixes a related issue include it in the commit message. Ex: [Fix #issue-number]
Tests are added or updated if you fix a bug or add a feature.
CHANGELOG files are updated for the changed libraries if there is a behavior change or additional feature. Minor bug fixes and documentation changes should not be included.

…o next.

railties/lib/rails/generators/rails/app/app_generator.rb

monfresh · 2023-03-10T01:56:17Z

railties/lib/rails/generators/rails/app/app_generator.rb

+
+          Rails project created and dependencies installed.
+
+          Now switch to the directory where the Rails app was created:


This is great! I wonder if this should be behind a conditional in case they're already in the Rails app directory. For example, I typically create the directory first, then cd into it, then run rails new .

rafaelfranca · 2023-03-10T02:33:43Z

This is great, but I have a question. how people know about how to install Ruby, how to install Rails and how to generate a new rails app but didn’t find at least some documentation about rails yet?

rafaelfranca · 2023-03-10T02:43:58Z

railties/lib/rails/templates/rails/welcome/index.html.erb

@@ -82,6 +86,10 @@
    </a>
  </nav>

+  <section>
+    <p>Edit your Rails app code at <code><%= Rails.root %></code> and build something amazing.</p>


How is this information useful given the person already started the server and it is already in the folder? Don’t they already know where the code is?

Another option is to link to the getting started guide instead. I could see the folder where the app is defined being useful if we have some kind of “one click installer” that would generate an app to you and start a server, but so far I’m not aware of any, neither I think we should optimize this page for this case.

Sending folks to guides feels like it gives them too many "choices" and would "throw the book at them"

At this point I think the mindset is, "how do I make this screen go away?". Some ideas I had around that:

"Edit the Rails.root.join("config/routes.rb") routes file and connect this application to a controller"

The language isn't perfect there, but better than nothing.

The developer would open config/routes.rb and maybe there's a comment in there telling them to generate a resource of scaffolding if its their first go at a Rails app.

I like that better. Can you update the pr to point to the routes please?

It's now pointing to routes.

I also confirmed that the routes file has a "next step" in it:

Define your application routes per the DSL in https://guides.rubyonrails.org/routing.html

rafaelfranca · 2023-03-10T02:45:44Z

railties/lib/rails/generators/rails/app/app_generator.rb

+
+          Then boot the development server:
+
+            $ ./bin/rails server


There is not need for ./ here.

Both instances are removed

rafaelfranca · 2023-03-10T02:47:01Z

railties/lib/rails/generators/rails/app/app_generator.rb

+
+            $ ./bin/rails help
+
+        NEXTSTEP


Maybe we should add a link here to the getting started guide, specifically in the section after how to generate the app?

To keep it brief, somewhat generic, and robust against the URL changing, I added this blurb:

More help is available at https://guides.rubyonrails.org/

I left out the API docs and a lot of other links because they can figure that out when they head to Guides and I don't want to overwhelm with a big list of links.

rafaelfranca · 2023-03-10T02:49:01Z

railties/lib/rails/templates/rails/welcome/index.html.erb

@@ -82,6 +86,10 @@
    </a>
  </nav>

+  <section>
+    <p>Edit your Rails app code at <code><%= Rails.root %></code> and build something amazing.</p>


Another option is to link to the getting started guide instead. I could see the folder where the app is defined being useful if we have some kind of “one click installer” that would generate an app to you and start a server, but so far I’m not aware of any, neither I think we should optimize this page for this case.

bradgessler · 2023-03-16T20:51:27Z

I'm reasonably happy now with the "flow" we're giving new Rails users. The Home Screen could probably stand to link to the guide and have a few other improvements, but this PR eliminates all of the "brick walls" that people might encounter during their first go at a Rails App.

If it looks good I can squash everything (or leave it as is, whatevs) and do whatever cleanup is needed to get this into main.

dhh · 2023-03-17T01:19:25Z

Like the reminder on how to start a server. Not loving the path added to the splash screen or the other points.

Ultimately, I don't think we should be solving for "what if someone installed rails but didn't have any other guidance at all" in the new app flow. Not realistic or even doable.

The foundation will soon be commissioning a new first tutorial. That's the place we should be driving the first encounter from.

bradgessler · 2023-03-28T19:06:33Z

@dhh I'm not sure what to make of your comment. From what I can tell you're stating a preference, but leaving the PR as it currently stands seems to satisfy everybody else's goals of making Rails marginally easier for people just getting started.

I don't think there's an expectation of, "what if someone installed rails but didn't have any other guidance at all"—it's more a matter of putting signs up on the road that assure people who are running through the tutorial that they're the right path. by that logic, signs and maps/guides are complimentary, not mutually exclusive.

rafaelfranca · 2023-03-28T21:20:19Z

I agree with David in the general idea and in the specific that this change in the welcome page doesn't add much value. But I'm ok with the next steps banner. It is very common to see people generating a new application and not knowing they need to cd to the directory.

@bradgessler what do you think of leaving out the welcome page change, and move on with the next step banner in the generator?

bradgessler · 2023-03-29T00:06:16Z

That seems reasonable. I think more could be done to the welcome page in a different PR to make it more useful and at least on par with Phoenix, Laravel, etc.

K so my next steps are:

Remove the welcome screen message
Squash all the commits

Chime in if I'm missing anything. I've got a few other things on my plate right now so it might be a few days before I finish the few things above.

dhh · 2023-03-29T14:27:31Z

I think either we point to rails help or we point to the guides, but not both. Then fine keeping the rest of the next step banner, and removing the stuff on the splash screen.

Add text to the "Welcome to Rails" screen that tells people what to d…

bb79f63

…o next.

rails-bot bot added the railties label Mar 9, 2023

bradgessler force-pushed the first-steps branch from cc837c2 to 9bb53b5 Compare March 9, 2023 21:05

p8 reviewed Mar 9, 2023

View reviewed changes

railties/lib/rails/generators/rails/app/app_generator.rb Outdated Show resolved Hide resolved

Add a next steps banner after rails new

40c3e9b

bradgessler force-pushed the first-steps branch from 9bb53b5 to 40c3e9b Compare March 9, 2023 22:28

monfresh reviewed Mar 10, 2023

View reviewed changes

rafaelfranca requested a review from dhh March 10, 2023 02:30

rafaelfranca reviewed Mar 10, 2023

View reviewed changes

Change welcome CTA with to edit the routes file

3a68087

Link to the guides

9be6701

bradgessler force-pushed the first-steps branch from b3c157a to 9be6701 Compare March 16, 2023 21:07


		Rails project created and dependencies installed.

		Now switch to the directory where the Rails app was created:

Add more guidance for people who are creating their first Rails app #47620

Are you sure you want to change the base?

Add more guidance for people who are creating their first Rails app #47620

Uh oh!

Conversation

bradgessler commented Mar 9, 2023

Motivation / Background

Detail

Additional information

Checklist

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rafaelfranca commented Mar 10, 2023

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bradgessler Mar 16, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bradgessler Mar 16, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bradgessler commented Mar 16, 2023

Uh oh!

dhh commented Mar 17, 2023

Uh oh!

bradgessler commented Mar 28, 2023

Uh oh!

rafaelfranca commented Mar 28, 2023

Uh oh!

bradgessler commented Mar 29, 2023

Uh oh!

dhh commented Mar 29, 2023

Uh oh!

Uh oh!

bradgessler Mar 16, 2023 •

edited

Loading

bradgessler Mar 16, 2023 •

edited

Loading