Explain differences between tutorial and howto

[camerons]

Tamanna Sethi 14:42 14 Nov ... At a glance, How-to and Tutorial templates look similar. It will be better if we explain their use cases better.

Cameron: [And we probably should include a reference to these differences from within the templates themselves]

[mgan59]

Posting here the current description in the Readme

Template name	Documentation type	Description
How-to	Task	Short series of steps for a particular task
Tutorial	Concept, Task	A training document for a product or topic

[flicstar]

Yeah cool, thanks Morgan. I think the How-to description is good.

I would suggest updating the Tutorial description to something like "A collection of How-to procedures for learning a product or topic. Typically a longer document than a How-to." Off the top of my head.

[Loquacity]

I wonder if it's worth drawing a distinction between these using "process" and "procedure". A process contains many procedures, so a Tutorial is a process, while a How To is a procedure.

[camerons]

I'll throw in https://documentation.divio.com/ as a good description of four doc types, including Howtos and Tutorials.

[waldyrious]

I'll throw in https://documentation.divio.com as a good description of four doc types, including Howtos and Tutorials.

I fully subscribe to that resource as a great model for distinguishing between tutorials and howtos, and to structure documentation in general. From my understanding, here is the gist of how they define them:

• Tutorials are quick-start guides, aimed at beginners, and usually present a simplified model of the system to help them learn the ropes and get started, by means of a hands-on exercise. Tutorials are typically a demo/toy project, similar to a school exercise or "hello world". Their focus is on demonstrating the tool itself, rather than on the output of the exercise.

• How-to guides are for the readers who already know the basic concepts of the system, and want to accomplish a specific task with it. They offer a step-by-step recipe to solve a real-world, common problem, serving as a demonstration of practical use cases. The focus is on the end result, rather than in the tools used to achieve it.

[aidanatwork]

I also support using the distinction as outlined by Divio's documentation system. One of the key differences is that a Tutorial assumes much less product-specific knowledge going in and the end result should be the reader actually creating something that works (ex: "Hello World"), even if it is too simple to be a realistic use case. The key action is learning.

With a How-to Guide basic familiarity with the product is assumed, and you are just providing a "recipe" for one real use case. The key action is doing.

To use a cooking analogy, a YouTube cooking tutorial might walk you through every step of baking a plain cake sponge, without any frosting or flavoring. It would explain the details of how to use a measuring spoon, keep your preparation space clean, suggest purchasing a cooking timer, etc. A cooking How-to Guide by contrast would just be a recipe: a list of ingredients and numbered steps to bake a specific real cake, say a Pineapple Upside-down Cake.

I'll take a look at these descriptions and take a stab at revising them.