Tutorial feedback and ideas

[developit]

Feedback and ideas for preactjs.com/tutorial!

[developit]

Feedback from this week's hackathon:

• Completing the tutorial takes longer than 10 minutes!
• There should be a Table of Contents for each topic (easier to refer back to)
• There should be a feedback form for tutorial and/or place to submit typos (potentially this thread!)
  • link to this thread from the tutorial

[JoviDeCroock]

Made #816 to add this link to the ending screen. Do you think longer than 10 minutes is a problem? I think we cover a good amount of pieces with sufficient conceptual information, we can cut a bit here and there but imo 15 minutes shouldn't be an issue 😅

For the table of contents, we could have a step-thing at the top like some bubbles with the titles

[TheYuriG]

Do you think longer than 10 minutes is a problem?

Sorry for replying to this over a year later. I just finished the tutorial and think it goes in-depth enough to teach you the required concepts. Making it shorter would most likely make it more barebones, which is not good.

[cknight]

Brand new to both React and Preact going through the tutorial for the first time. Here's my feedback:

• Some more info on the component lifecycle would help
• I found hooks very confusing. Also the tutorial (and 'Try It!') uses useMemo which I had to look up as it wasn't discussed at all in the tutorial.
• I probably more than 10 minutes on each tutorial page (though you may be targeting more experienced React developers) so the learn preact in 10 minutes is a bit of a stretch :)
• console.log statement output didn't appear anywhere I could see (I'm using Brave fwiw). I ended up having to switch to alerts.
• 'Help' overwrote my solution with the 'correct' one. It would be nicer experience to see the solution without overwriting the work already done as I would have liked to finish it on my own after peeking at the bit I was stuck on.
• Jumping back and forth between classes and functions was confusing.
• Finally, thanks! Really enjoyed the tutorial and the applying your knowledge via the editor was great.

[developit]

This is all super useful feedback! Thanks a ton for taking the time to articulate it @cknight. I think we can address a few things right away, and I'd really like to find creative ways to handle the classes/functions and hooks intro points (strong agree on both).

[cknight]

Just to add a little more detail, here's a code snippet from the editor (specifically from https://preactjs.com/tutorial/02-events) which fails to log to the dev console:

export default function App() {
  return (
    <div>
      <p class="count">Count:</p>
      <button onClick={() => console.log('hello world')}>Click Me!</button>
    </div>
  )
}

[TheYuriG]

• 'Help' overwrote my solution with the 'correct' one. It would be nicer experience to see the solution without overwriting the work already done as I would have liked to finish it on my own after peeking at the bit I was stuck on.

This was an issue for me too, but thankfully I could ctrl+Z to return to my own input. Would be nicer if the Help button would create an overlay that you could close (or something), so you could click the X or click Help again to close.

[ghost]

This tutorial is very well done -- too much information presented succinctly. I've been able to understand class components, useRef, useMemo, etc. effortlessly after they've been dark corners to me in a multi-week React course I took. Still the feasibility of going through it in 10 minutes is an unsolved puzzle.

[JoviDeCroock]

Thank you for the feedback, very much appreciated. Do you have any idea's on how to handle the too much information or the 10 minutes asepects?

[rschristian]

We may want to switch "Learn Preact in 10 minutes" to simply "Learn Preact". I think it'd be quite hard to find a time estimate that's useful and accurate for the wide range of people that may read through it.

[ghost]

The length of the tutorial looks good to me. As @rschristian suggested, the title could be changed for example to something like Learn Preact in no time. A table of contents as previously mentioned (simple list of section names) could help set expectations for visitors.

[snej]

The tutorial’s fine as far as it goes, but it seems to leave out a lot of what’s in a real app. I ran npx preact-cli create typescript to create a basic app to play with, and there’s a lot of stuff in the app I don’t see any docs for:

• There’s a whole package preact-router that seems to do request routing in a PWA, providing components like Route, Link and Match.
• Many of the components are importing CSS stylesheets as though they were JS modules … um what?!

I’m left with the feeling that I only understand the surface level of Preact and am not ready to start building an app yet, but I don’t know where to go next. Maybe reading the JS source code?

[Update: I found a fairly clear README for the router.]

[rschristian]

It's important to distinguish Preact from tools used to build apps, which may or may not be Preact-specific. Part of the unfortunate reality of the past ~8 years of front end development is that a UI library like Preact is just a tiny piece of the puzzle; by and large, you're also directly orchestrating a dozen other major tools and potentially hundreds indirectly.

If you've gone through the tutorial you do understand Preact! However, if you want to make a full web app, the UI library is just a singular (but important) piece of the puzzle.

There’s a whole package preact-router that seems to do request routing in a PWA, providing components like Route, Link and Match.

Indeed, preact-router is a tool used for client-side routing typically found in SPAs. It's one of two "official" Preact routers but there's a dozen or so very popular options that can also be used.

Many of the components are importing CSS stylesheets as though they were JS modules … um what?!

Importing CSS into JS modules indeed is one of the great "sins" (depending on who you ask) that have become normalized and standardized with build tooling. This isn't specific to Preact or Preact-CLI, nearly every tool does it, but it certainly can be a bit of a surprise.

CLI utilizes two different types of CSS imports: side-effectful (import './foo.css') which more or less associates a bit of CSS with a component, and CSS Modules (import style from './style.css') which is a build-time transform for scoping classes locally. You can read more about here: https://github.com/css-modules/css-modules

I get that this probably isn't an ideal answer, but how you build apps with Preact can change from project to project and isn't a core part of Preact itself.

[Stefan-Hanke]

I've just finished the tutorial.

On the last two entries(Keys/Error Handling) it's not obvious what is accepted as expected outcome. AND I literally just while writing this I found that Help button xD well maybe that's just me...

I personally found that showing syntactic errors while typing to be annoying to a point where I'd like to turn it off. It's not showing that error, but that lines after the error are shifted down, and it's hard to read the code in context since the function is now split in half by that inline error.

Otherwise, I'd like an indication about global progress, so I can decide whether to continue the tutorial or maybe shift it to later.

However please do note that these are nitpicks and I enjoyed taking the tutorial due to its brevity and small tasks - remembers me about the old Addison-Wesley workshop books which I am still fond of. They did not offer just a solution to the problem, but before that two hints in increasing explicitness towards the solution.

Thanks!

[developit]

woah, thanks for the awesome feedback @Stefan-Hanke! Totally agreed about the errors-as-you-type, especially since they shift the text around. The progress indicator is a great idea too! TBH I don't even recall what we check for in the solution for the last two chapters, maybe that's a sign they're too open-ended 👍

[TheYuriG]

I don't know if this is within the bounds of your control (as I assume the tool used is external to Preact), but would be nice if the editor had a little bit of debounce on it, because having it display errors WHILE I'm typing is a bit annoying.

I know that code won't compile and run, I'm literally typing it, chill for a minute. I ended up needing to type my code inside a comment block, then uncomment it to avoid errors.

Also, maybe if possible, add a beautify button to the code editor so it can have proper indentation after we typed our code?

[jspc]

It'd be great if the tutorial covered testing.

Using, for example, npm init preact to bootstrap a project (like the preact getting started page suggests) doesn't configure or do anything with tests like create-react-app does, for example.

This would be great to see here- the rest of the preact docs cover all kinds of wonderful options for testing, and all kinds of exciting looking tools and projects but there's nothing that seems to cover "Here's how you configure tests, here's how you run them, here's what the options are" that's geared to the same audience as this tutorial.

There seems to be an assumption in the existing docs that the audience already understand all of that, which the tutorial (refreshingly) doesn't assume.

[rschristian]

I don't think that would fit in the tutorial (it's a tutorial in using Preact, not how you could manage Preact projects), but I do agree, setting up basic testing tools is something missing from our docs.

I created #927 a while back to track.

[jaime-ez]

great tutorial. after coding react for a long time I finally understand the core concepts. Just put an hyperlink to the definition of each new concept/function that is presented (for instance useMemo). Great job anyway!