Hacker News new | ask | show | jobs
by zahlman 259 days ago
Applying the diátaxis (https://diataxis.fr) wisdom here: what you describe is really a how-to guide rather than a tutorial. These are also important, and you should seek them out (and ask for them) when they're what you want.

Tutorials fundamentally exist to serve a different purpose: to orient people within the subject matter, when they don't even know what question to ask. Going through steps in order is important so that the student can focus. Intentionally going down wrong paths can be counterproductive for the neophyte, because it means having about as much experience doing the wrong thing as the right thing. Debugging is a general skill, but technology-specific debugging can and probably should be taught separately from the "happy path".

A properly done tutorial will properly show the steps, and will have been tested to ensure that it can in fact be expected to work on everyone's machine. The parameters for success will be controlled as tightly as possible.