Hacker News Reader

Parent Full thread

cmehdy

It all seems close because the terms are muddied in our minds by countless poor instructions over the years.

Their doc actually explains the difference efficiently though :

Tutorials - learning-oriented experiences

How-to guides - goal-oriented directions

Reference - information-oriented technical description

Explanation - understanding-oriented discussion

View on HN

But I want to learn something in all of those examples. I have a goal in all I do. I need technical information in all as well and I want to gain understanding in all of those as well. It really is just a bad way to name these categories. I haven't thought about how to do it better yet, I personally like the ziglang docs where everything is presented as a huge reference document with examples in each section. The only additional thing that is needed is usually something like APIs and executable code. Of course the reference document can also have executable samples like what Stripe does. But somehow I think a dedicated section for example code is legitimate in addition to a long reference.

Reply on news.ycombinator.com