Comment by arjenschat | Hacker News Reader

Comment by arjenschat | Hacker News Reader

Parent Full thread

What we've learned is that you can roll the how-to guides and tutorials into one. Once a users has learned how to use a service, they only need some inspiration on how to use it in different scenario's

Van der Meij, H Wrote a nice article [1] about minimalism in documentation referring to the first how-to guide (First_Minimal_Manual) [2] on how to use smalltalk for an IBM Displaywriter System (1980). This guide is all about just getting started, and if something goes totally wrong, you just reboot the machine.

People learn by doing. For new user, unfamiliar with your service, you have to reassure them that they can undo everything. This allows them to explore the system freely without any anxiety of doing something permanently wrong.

People prefer to be shown what todo instead of being told what to do. Ikea and Lego manuals for instance never tell you to put screw B1 into hole 7A in the right side of panel 14B Screenshots in your help center articles help a great deal with this. But these are hard to maintain, that is why we created Cliperado [3]

[1] https://www.utwente.nl/en/bms/ist/minimalism/

[2] https://www.utwente.nl/en/bms/ist/minimalism/displaywriter.p... (PDF)

[3] https://cliperado.com

That is interesting - my experience is the opposite, that how-to guides and tutorials are the most-commonly confused types of documentation. My aim is to make the serve totally different needs:

* tutorials: I'm in charge (the teacher) and I know what the new learner needs to grasp and become comfortable with so that they gain sufficient basic confidence and skills. In the tutorials, the beginner doesn't even know what questions to ask or what language to us when asking questions

* how-to guides: the user is in charge; they are able to formulate the questions, and have the basic confidence and skills. What they need from me are the recipes.

As described, it's the difference between teaching a child to cook, and a book of recipes for somebody who already knows the basics of cooking and the kitchen but wants to know how to cook a particular thing.

If you get teaching a child to cook mixed up with a book of recipes everybody concerned will have a bad time. It matters most for the child, they will never want to learn how to cook with you again.

The same go for tutorials in my experience.

The issue is that tutorials and how to guides signs like the same thing. I prefer to use getting started and how to guides.

I do that sometimes too: https://brachiograph.readthedocs.io/en/latest/get-started/in....

As long as your tutorials aren't so basic as to be useless in practice you can roll them together sure.

Reply on news.ycombinator.com