Onboarding first impressions

Here are my first impressions of Redwood’s onboarding, with suggestions on what you should change, sectionned by pages.

https://redwoodjs.com/

Not everyone knows what the JAMStack is. A link to JAMStack is needed, unless repelling users who don’t know what the JAMStack is is part of your strategy.

Not everyone might also know what GraphQL and Prisma are but I don’t think the absence of links is a problem there. JAMStack is fundamental to Redwood, React/Prisma/GraphQL are implementation details.

The call-to-action button links to /tutorial, which redirects to /tutorial/welcome-to-redwood.html. You might want to directly link to /tutorial/welcome-to-redwood.html to improve performance.

There’s an aside HTML element that’s floating over the right side of the page, starting at the newsletter block. It prevents text from being selected. This element needs to go, but simply removing it messes with the layout; a hack is simply to add pointer-events: none in CSS to it so that what’s underneath can be interacted with.

In the section “How it’s Organized” the bottom right text “downloaded as needed” on the image is hard to read, at least on a non-retina screen. “The internet” is also hard to read. It must be even worse on mobile. The ability to open the image would be nice.

In the “Routing” section you would expect the users route to have an username param, not a type, this is slightly confusing. Not good for the first code demo. You might want to include another example.

In the “Services” section it says “Redwood does all of the annoying stuff for you.”. It’s not clear what is that annoying stuff.

In the “Generators” section, in the code example it reads “create the SDL file”. If you don’t know GraphQL, you don’t know what SDL is, or even that it’s related to GraphQL. I suggest replacing it with “GraphQL SDL” to succintly help understanding that it’s something related to GraphQL and not something part of Redwood that’s not explained.

The list of commands in the Generators section look like a lot of command to remember. You might want to specify that there’s a command to list all those commands. (If there isn’t one, there should be one.)

In the “Forms” section, if “Working with forms is notoriously annoying in React apps” (I don’t know much about React) and Redwood fixes that, it should be spotlighted more. I recommended placing that section right after the “Cells” one.

In the bottom page’s call to action it says “Ready for Redwood?”. A user doesn’t really know if they’re ready, I suggest removing that text and simply leaving the “Start the Tutorial” button, while making it (much) bigger.

GitHub - redwoodjs/example-todo: Example Todo app written with Redwood

For each listed feature and its associated file you’ll want to write in what folder the files are. This demo is linked at the top of the GitHub’s Readme (itself linked in the Welcome to Redwood tutorial page) and at this stage you don’t yet know how folders are organized. (As a result I haven’t bothered checking where the files are, they’re neither directly in web nor api).

“We use Yarn”. It’s not clear that Yarn is required and the reader might be tempted to use npm. I recommend changing it to “We require Yarn”.

Same thing on GitHub - redwoodjs/example-invoice: Example Invoice app written with Redwood

GitHub - redwoodjs/example-blog: Example Blog app written with Redwood

Typo → “SQLite is the easist”

(I haven’t read the readme in full there.)

redwood/README.md at main · redwoodjs/redwood · GitHub

In the Technologies section it says “The end result is a JavaScript development experience you can fall in love with!”. The exclamation point is too much, I recommend a simple dot.

That’s a lot of technologies, do you need to know them all to use Redwood? Can you start using Redwood without knowing them? If the latter answer is yes it would be good to indicate so.

In the Features section, “Hot module replacement (HMR) for faster development.”. It’s better known as Hot reloading, so I suggest changing it to “Hot reloading (Hot Module Replacement)”.

“First class JAMstack-style deployment to Netlify.” suggests it needs to be deployed on Netlify. If it can be deployed elsewhere it should be specified.

In the The Redwood philosophy section, “Redwood believes that JAMstack is a huge leap forward in how we can write web applications”, I suggest changing “we” by “you” to make it cognitively easier to understand that there’s something in it for the reader.

“Redwood believes that there is power in standards, and makes decisions for you” → “and thus makes”

“a developer should be able to jump into any Redwood application” → Change to “is able to jump” as soon as you’re confident in your framework.

“However, that does not mean that Redwood doesn’t shine with NoSQL” Double negation. Change to “However, Redwood also shines with NoSQL”.

“you should be able to operate in a serverless mindset and deploy to a generic computational grid” What’s a generic computational grid? Can it be explained in a more straightforward way?

“Redwood believes that deployment and scaling should be super easy.” → “your deployment” to better convey “what’s in it for me?” to the user. Especially useful there as the two next sentences contain “you/your”.

“Redwood believes that it should be equally useful for writing both simple, toy applications” Who wants to write toy applications? Change to “simple applications”.

In the How it works section, “For clarity, we will refer to these in prose”, “prose” is a word that’s not usually completely clear for those that don’t have English as their native language. I recommend removing “in prose”, the text is as clear (and not as demanding) without it.

“It is important that you keep this distinction clear in your mind as you develop your application.” It’s very simple to keep that in mind, so I recommend removing that sentence.

“Redwoods are beautiful as saplings, and grow to be majestic. What if you could feel that way about your web app?” Quite touchy-feely. I would put that point last.

“Surprisingly robust to disaster scenarios, just like a great web framework should be!” The exclamation point is too much.

The Readme should end with a call to action to start the tutorial.

Prerequisites | Learn RedwoodJS

The instructions to install Yarn and Node.js start with Mac and end with Windows. Windows is twice as popular and its explainations are shorter, so I recommend putting Windows first.

The next page in the tutorial says that Yarn is a requirement. Humans respond better to things when they’re given an explaination for why something is so. I recommend explaining why Yarn is required, on the Prerequisites page.

Installation & Starting Development | Learn RedwoodJS

“We’ll use yarn (yarn is a requirement)” → remove “(yarn is a requirement)” if you follow the previous recommendation.

Also it’s spelt “Yarn”, not “yarn”.


That’s all I have for today. Not sure if I’ll continue, I was looking at Redwood out of curiosity and not out of a need – I personnaly believe in vanilla JavaScript for the projects I do.

2 Likes

Hi @dieulot! First off, welcome to the nascent Redwood forum and huge thanks for both helping us get started and all the time + effort evident in your post above. We don’t take any of that for granted.

I’m looping in @rob here as well.

Some thoughts and possible next steps:

  • Any website content errors + fixes are most helpful coming as a Pull Request. We are a super small team and this is a large community project, which means we extra :heart: collaboration. The repo is here: GitHub - redwoodjs/redwoodjs.com: redwoodjs.com redesign for 1.0
  • Without trying to discourage help like this, the challenge for us is that it’s just too much for us to process and get to. (Again, it’s that whole “small team” thing.) The quality and advice are great, but for us, it’s simply not actionable unless it’s less at a time plus structured and/or prioritized. Does that make sense?

Last but not least, at this point we mostly want to know what you think of the actual framework itself? So your final comment is of 10x more value to us:

Not sure if I’ll continue, I was looking at Redwood out of curiosity and not out of a need – I personnaly believe in vanilla JavaScript for the projects I do.

I’m curious about your needs specifically, e.g. what are you building and what audience are you building for? Maybe Redwood isn’t a good fit, which makes sense. But that kind of feedback helps inform us as we build features and improve the overall experience.

Thanks again!

1 Like

Sorry, I can’t provide any more help. Compiling that post was already a dubious use of my time.

I build simple sites with great UX, including great web performance, so I don’t want to include hundreds of kilobytes of JavaScript.

Good luck with your project.

1 Like

:+1: Understood. And same to you!

1 Like

@thedavid Maybe a short guide on installing database,

You also have make sure that you have SQLite database installed.

For installing sqlite on,

windows choco install sqlite

ubuntu sudo apt-get install sqlite3

mac brew install sqlite

1 Like

Ah, great catch @guledali I think overall we need a “troubleshooting” guide as well. I’ll create an issue for us in our GitHub redwoodjs/redwoodjs.com repo and add your notes above.

Thanks!

From what I understand Prisma ships with a SQLite library and doesn’t require any external dependencies

1 Like

Yes indeed! See this “Prisma2 supported DB” list and SQLite info at the bottom. I think Windows users were running into an issue, which is where this questions/how-to came from.