Here are my first impressions of Redwood’s onboarding, with suggestions on what you should change, sectionned by pages.
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.
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”.
Typo → “SQLite is the easist”
(I haven’t read the readme in full there.)
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.
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.
“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”.