First-time user experience friction

[sophiajt]

Bevy version

97d8e4e1793ede3df8c77ed44736e800b38ff7a4

Operating system & version

Manjaro Linux

What you did

I've tried to learn Bevy a few times but each time I've bounced away. I wanted to capture a few things that I think contributed to bouncing away as part of the data for the new user experience for your project. Hopefully this is helpful.

I come to the Bevy website to learn Bevy and luckily there's a Learn button at the top. This is great! I can easily go in this direction to learn Bevy. After clicking it, I'm given four options. None of these options are tutorials on how to learn Bevy, so I try to guess what might be second best. I click on the book to learn Bevy.

Great, let's get started.

I click the book and the first thing I see is a stability warning. Fair enough, it's pre-1.0. I click next, then follow the instructions to checkout Bevy. Great, now we're cooking. I follow the next step to run the example.

And this is where I run into my first issue. After I finish playing the breakout example I expect the game to restart or exit. Neither happens. So I hit esc to exit. Nothing happens. 'q'? Nope. Ctrl-C? Nope. Okay fine, I'll use the mouse. I close the example clicking the X button and the window closes but the example is still running. So I have to manually ctrl-c out of the window-less app. At this point I'm a bit confused. How are you supposed to quit the example? If the examples are there to teach people how to use your system, surely you'd want to teach them how to exit properly.

I press on. Moving to the 2.1.setup section of the book, I scan through and this all seems mostly okay. I get stuck for a bit in the Optional setup section, trying to decide if I should go through the trouble of setting up a new linker. At this point, I'm already about ten minutes in and still haven't gotten to any code other than "hello world" and an example that didn't quite work.

I'm starting to feel a bit lost. The black background of the book is sapping my energy to move on. I want to make a pretty game, and this is really killin' that vibe. Okay, let's see if we can get a little further this time.

I click ahead a bit and land in the ECS section. I've got at least a little familiarity with ECS from other engines, so I think this will be fine. By the end of the ECS page, we're still printing the equivalent of hello world.

What you expected to happen

I think the issue I'm hitting is that for my 15 minutes of investment, I'd love to be able to do more. I think of when I first started playing with SDL and in those same 15 minutes how much faster I could have something drawing on the screen and be off to the races.

There's always going to be a ramp-up time, but those first 15 minutes are precious. If you can deliver wins in those 15 minutes, it helps propel people like myself forward. Get an early success and then build success on top of that success. And so on.

What actually happened

See above :)

Additional information

Happy to chat more.

[bjorn3]

I close the example clicking the X button and the window closes but the example is still running. So I have to manually ctrl-c out of the window-less app.

This is a bug: https://github.com/bevyengine/bevy/issues/2030 I would guess it is some kind of problem in winit, but I am not sure.

[alice-i-cecile]

Thanks! This is excellent, actionable feedback. Improving the new user experience is high on my priority list, and making the Book better (see https://github.com/bevyengine/bevy-website/pull/102 for more discussion) is one of the most important things to do.

As for nice quitting behavior, I've made a new issue for this: #2110. Should be an easy win :)

[cart]

Thanks for the feedback! We don't get enough of these "onboarding retrospectives".

This is great! I can easily go in this direction to learn Bevy. After clicking it, I'm given four options. None of these options are tutorials on how to learn Bevy, so I try to guess what might be second best. I click on the book to learn Bevy.

Hmm I'm not sure how we can improve this. The Bevy Book list entry has the text "Learn how to use Bevy using this step-by-step guide. If you are new to Bevy, you should probably start here". It doesn't have the word "tutorial" in it, but its pretty explicit imo. We also need a section on that website that lists multiple learning resources. We already put The Bevy Book at the top of that section and we have the big blue "Get Started" button in the headerbar that directly links to the "getting started" section of the book. What would you change here?

So I have to manually ctrl-c out of the window-less app. At this point I'm a bit confused. How are you supposed to quit the example? If the examples are there to teach people how to use your system, surely you'd want to teach them how to exit properly.

Yup this isn't super ideal. Some games might not want to immediately quit on exit (ex: they might ask you if you want to save first, or ask for confirmation), but quitting by default (or showing people how to quit in examples) seems reasonable. We'll need to discuss the ideal behavior and the #2110 issue @alice-i-cecile created seems like a good spot for that.

I think the issue I'm hitting is that for my 15 minutes of investment, I'd love to be able to do more. I think of when I first started playing with SDL and in those same 15 minutes how much faster I could have something drawing on the screen and be off to the races. There's always going to be a ramp-up time, but those first 15 minutes are precious. If you can deliver wins in those 15 minutes, it helps propel people like myself forward. Get an early success and then build success on top of that success. And so on.

This is a solid point. The Book hasn't gotten enough love since the initial Bevy release, but we're working on improving that now. The "deliver big wins in 15 minutes" rule you called out is a great thing to keep in mind when we start writing new content.

[sophiajt]

@alice-i-cecile @cart - thanks for the encouraging feedback!

The Bevy Book list entry has the text "Learn how to use Bevy using this step-by-step guide. If you are new to Bevy, you should probably start here".

FWIW, we have a similar issue with Nushell right now as well. We have a book that has an install/intro/etc to help folks get all setup and going, but we don't have a streamlined tutorial. Some users have told us "I don't want to read a book to get started" which I think is a fair point.

If you can manage to get people up and running using the book in 15 mins, that might be good enough. Alternately, having a tutorial that gets you quickly setup (without any extra info about optional configurations) and a single simple project to accomplish (like a bouncing ball) helps give that quick first win.

I suspect at least some number of your potential users will want to do a quickstart first, get that running, and then use the book to deepen their knowledge.

[alice-i-cecile]

I suspect at least some number of your potential users will want to do a quickstart first, get that running, and then use the book to deepen their knowledge.

This is a neat idea; it might be nice to split this out between a Quickstart and a Book.

[alice-i-cecile]

These are being tackled nicely with the new book. I'm going to close this out; further work is being tracked on the bevy-website repo.