Little Gestures of Confidence Make Our Tools & Community Better

The world is a much better place when we say “please” and “thanks” as we go about our daily lives. The same should be true for the tools, frameworks, documentation, and code we use in Ruby—and a little effort can go a really long way to build confidence in people who are just getting started.

Rails is the 500lb gorilla in the Ruby world, so lets pick on it for a second. As of Rails 7.0, here’s what people see when they run rails new on their command line.

$ rails new hello-rails
Ignoring rbs-2.8.2 because its extensions are not built. Try: gem pristine rbs --version 2.8.2
      create
      create  README.md
      create  Rakefile
# ... A bunch of stuff happens here ...
Appending: pin_all_from "app/javascript/controllers", under: "controllers"
      append  config/importmap.rb

Then, somehow, they have to figure out how to boot the development server via bin/rails server and see this screen.

The screen tells us what version of Rails we’re running and the Ruby version. That information might be helpful for people who are running multiple versions of Ruby and Rails on their machines, but it doesn’t really tell people what to do next.

If this our first time in Rails we might look at that screen and wonder “uh … ok? Now what?”. Each little pause and utterance slowly chips away at the confidence people who are just getting started with Rails. It’s not a good look if we want to attract more junior engineers to the ecosystem.

We can do better!

Tell People What They Should Do Next

What if instead of letting people slam walls we give them little hints of what to do next? It’s really not that much extra effort to give people this experience.

$ rails new hello-rails
Ignoring rbs-2.8.2 because its extensions are not built. Try: gem pristine rbs --version 2.8.2
      create
      create  README.md
      create  Rakefile
# ... A bunch of stuff happens here ...
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

Let’s do the first thing and boot the development server.

It doesn’t seem like much, but little morsels of what’s next prevent the gremlins of self-doubt and imposter syndrome from chipping away at a new persons’ confidence. “Oh cool! I can go there and start editing my project code”.

The best part? If you’re a seasoned Rails veteran, these little things don’t really get in your way. Win win!

So Many Possibilities

There’s all sorts of possibilities to improve this flow to instill confidence in people who are new to the ecosystem.

• A link to the Rails Guides and Documentation
• Tell the person to run rails help from their project folder or display the commands on this page.
• Give them a specific command to run like rails generate scaffolding Posts title:string content:text so they can experience a quick “ah ha!” moment.
• Link to the Rails Forums or Discord community for help.

The list goes on, and there’s some great examples of Frameworks out there doing this, like Phoenix.

$ mix phx.new hello
* creating hello/config/config.exs
# ... A bunch of stuff happens here ...
* running mix assets.setup
* running mix deps.compile

We are almost there! The following steps are missing:

    $ cd hello

Then configure your database in config/dev.exs and run:

    $ mix ecto.create

Start your Phoenix app with:

    $ mix phx.server

You can also run your app inside IEx (Interactive Elixir) as:

    $ iex -S mix phx.server

Then after booting the server we see a page that links to guides & docs and the Elixir community.

What a difference!

Don’t be Overwhelmingly Helpful

It’s tempting to want to do All The Things^TM and provide a huge list of links to users to get them started, but you’ll want to be careful that you don’t overwhelm people with too many options.

Think of the first day on the job or at a new school—there’s lots of stuff coming to you all at once. Under those circumstances, its best to consume information in little bite-size morsels.

We Can All Help!

If you maintain open-source libraries, documentation, or any parts of the Rails and Ruby ecosystem, try running through whatever your new workflow is and make sure you’re always giving people a path forward that instills confidence and doesn’t overwhelm.

It might not seem like a big deal, but if enough people do it, the entire ecosystem will be just a tad more welcoming to people who are just getting started. I opened a pull request on the Rails Github repository with the ideas from above—what are some things you can do to help make Ruby more welcoming to the next generation of developers?

Let’s do this! 👊