Comment by cmehdy
2 years ago
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
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.