Yew: Improved onboarding experience

[ralfbiedert]

Description

I'm submitting a ...

• feature request - please describe the behavior you want and the motivation.

Overview

It would be nice if Yew had an onboarding experience like Elm.

I remember I stumbled across Yew a few months ago, but did not realize what it was about.

About two weeks ago I learned about Elm (mainly through the web page elm-lang.org), and thought to myself "I wish Rust had something like this".

Then, yesterday, I read a blog post about someone comparing web frameworks who mentioned Yew and Elm, and only then (after I knew what Elm was about) I came back to this page and could appreciate what Yew was really about.

Current Problems

Here are some problems and thoughts I had as a first-time user:

• Yew's documentation (README.md) starts with implementation details, comparing itself to Elm and WebAssembly. I think it's good to have that, but unless I know both, I don't really know anything.
• In contrast, elm-lang.org, starts with user (developer) values: JavaScript Interop, No Runtime Exceptions, Great Performance. I'm not saying that has go into the README, but whatever is considered the main entry point of Yew should probably have it.
• For the actual README (or whatever is considered the getting started), a super-simple "hello world" should be provided, along with "out of the box" instructions how to compile and run it. As of today, I have to either clone the repository to follow the instructions, and / or piece these things together manually (e.g., the README says to run $ ./ci/run_tests.sh; what if I don't have Bash)?
• After I successfully passed all of the above – I have my first "hello world"; how do I use it from a real page? How to interface with parts of an existing page should be next to the hello world.

[jstarry]

I've added documentation to https://yew.rs/docs/ and https://yew.rs/docs/getting-started let me know if they have the material you had in mind! Thanks for the issue!

[ralfbiedert]

The docs look great and I found them easy to follow and the actual landing page /docs is a clear improvement over the previous README.

I still think its narrative speaks primarily to a specific subset of Rust developers (those familiar with React, Elm, actix, async-await, wasm-bindgen; as the landing page primarily explains along those concepts).

I'd argue the page could be even better if it instead emphasized values that matter to web developers and their customers.

Elm

Elm sets the base line here:

• No Runtime Exceptions
• Great Performance
• Enforced Semantic Versioning
• Small Assets
• JavaScript Interop

These are 5 strong points I care about as a developer, and I care about them for my customers. Even more, I can use the same arguments to convince my manager or team (which might not even care about Elm or Rust) why this technology should also matter to them.

Yew

Right now the page lists:

• Architecture
• Concurrency
• Safety
• JavaScript
• HTML
• Why Rust?
• Why WebAssembly?

As a Rust developer I'd expect to find all of these terms on a Rust client web framework, but I'd have to actually read them to understand what they mean. For example:

• Architecture - Does that mean I can build a good architecture, or Yew has a good one? Oh, it says it's architecture is inspired by Elm and React. Again, I might not know these, so I'd have to look them up first and understand what makes their architecture great.
• Concurrency - Talks about async-await and actor models. Certainly interesting for Rust users which know about them.
  ...

In contrast, what if Yew could tie in its own strengths with those of Rust, maybe in two adjacent paragraphs. One addressing primarily people concerned with web values (why should I chose Yew over any other web framework), the other people concerned with Rust values (why should I chose Yew over any other Rust web framework):

Yew For Web Developers:

• Bare-Metal Speed (wasm ...)
• From User Interfaces to IO (actor model, concurrency)
• Reliable Code (no exceptions, ...)
• Seamless Interop (works well with existing HTML / JS if you have to) -- (TODO: does it?)
• Most Loved Language (no more JavaScript if you don't want; 1000's of Rust libraries to pick from)

Yew for Rust Developers:

• Modern Foundation (wasm-bindgen, async/await...)
• One Mental Model (actix actors, ...)
• Best of Both Worlds (fuses React model with Rust model)
• ...

I am not saying it has to be any of those, but something like that could be helpful on a landing page to immediately address a visitor's question "why should I care?"

[jstarry]

Great feedback, I've updated the docs, let me know your thoughts! Thanks in advance :+1:

[ralfbiedert]

Looks much cleaner, great improvement! I like that it focuses on a handful of strong points, and they resonate with me.

That pretty much covers my "onboarding" issues, thank you so much!

A few smaller design changes could be done later, but I don't think they are essential and probably just my taste:

• Maybe consider having a small diagram or "visual" code snippet for each of the 3 points (components, performance, interop) might look nice, similar to how React, or Angular do it.
• The points on the lower half are also good, but I find them a bit verbose.

[ralfbiedert]

I tried to create a PR but still had trouble getting the site to render properly.

Things I was experimenting with:

• Side-by-side images for "What is Yew" section turned out to be difficult in the current flow. For this style of page it's probably fine.
• Added a "Created with Yew" instead to lighten up flow, just an idea, can probably live without it.
• Added a more prominent "Getting Started" image
• Offloaded "Still not convinced" section to other page, incl. "Alternatives?"
• Changed flow to "What is Yew" -> "Ready to dive in" -> "Join Us"

Screenshot:

Again, not saying it has to be like that; more for myself to get a feeling for the page.

[ralfbiedert]

More compact version:

[Kelerchian]

Hi, guys

Just a suggestion: It'll be great if the examples folder is shortly advertised more inside the first few paragraphs so that people who prefer to read code AND who are not used to Rust codebase convention are informed that there are the examples folder. @jstarry helped me close an issue just now and it made me realize that yew has a lot of gems inside the examples folder. It's just hard to notice right now, at least for me.

And, another rough suggestion, I think yew will need the paradigm introduction like react does with https://reactjs.org/docs/thinking-in-react.html

[teymour-aldridge]

There is a link to the examples in the sidebar, do you think this does the trick?