Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

If you are writing a tutorial, please for the love of all that is holy do not just make it a bunch of copy/paste steps without much or any explanation. Make me work through it, debug it, take me down the wrong path on purpose for the "aha!" moments. Leave copious amounts of explanation and documentation. Tell me what can go wrong and how I can fix it. I do not want a video. I hate videos. I know not everyone does and people learn differently but videos suffer even worse from the copy/paste problem, I'm essentially just parroting what I'm watching usually without much explanation either. And also, going back and referencing is difficult without taking copious notes.

"Now we do x,y, z, and voila! here you have it, a fully fledged (whatever)." Ok, but what did you just do? Why doesn't it work on my machine? etc. I've seen tutorials that do this stuff right and it's a very obvious night and day difference.



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.


With any tutorial, don't just passively read it or copy/paste the code.

Take notes as you go. Type the code manually. Experiment with variations of the code. It does help your brain encode the information.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: