3 ms·

This is not a tutorial [1]. It's more like a guide [2]. [1]: https://documentation.divio.com/tutorials/ https://documentation.divio.com/tutorials/ [2]: https:

This is not a tutorial [1]. It's more like a guide [2]. [1]: https://documentation.divio.com/tutorials/ https://documentation.divio.com/tutorials/ [2]: https://documentation.divio.com/how-to-guides/ https://documentation.divio.com/how-to-guides/ Edit: I don't mention this to be nitpicky. I mention it because I wish that we would collectively start standardizing those terms. I think it would be helpful if, whenever we saw "… guide" or "… tutorial" we had a general idea about the structure and purpose of the contents. The Divio links above do a great job at explaining each doc type. I'm simply sharing this idea for people who have never considered being more careful about how they label their docs and would like to start following general technical writing community practices. As a practicing technical writer I can tell you that the TW community mostly agrees upon what each doc type entails ("tutorials" and "references" have strong consensus; "guides" less so).

dboreham 6y ago
'And thirdly, the code is more what you'd call "guidelines" than actual rules.'
useragent86 6y ago
I looked at those links. Here's what I got from them: 1. Tutorials "are lessons that take the reader by the hand through a series of steps." They "are oriented towards learning how." 2. How-to guides "take the reader through steps." 3. "How-to guides are wholly distinct from tutorials." If I found a "community" around a topic, do I then get to decide what words mean? By consensus, of course.
- xixixao 6y ago
  You can see a good breakdown of what they mean by each label in this table: https://documentation.divio.com/introduction/#the-secret https://documentation.divio.com/introduction/#the-secret It's certainly a valuable take, even if you disagree with the claim that all 4 functions are required for good documentation.
  - quietbritishjim 6y ago
    What specifically are you referring to in that table? The original article is a lesson on how to use JavaScript, from scratch, for a beginner. That perfectly fulfills all four requirements in the "tutorial" column: > oriented to: learning > must: allow the newcomer to get started > its form: a lesson > analogy: teaching a small child how to cook It does not satify all the requirements of any other column.
quietbritishjim 6y ago
This is a tutorial. It almost fits the definition of "tutorial" at the link you posted, but not quite, but that's because the definition at the link you posted is a bit flawed. It definitely is not a how-to guide, and the links you posted strongly support that. > How-to guides take the reader through the steps required to solve a real-world problem. That is from the linked article on how-to guide. By "real-world problem" it means something specific you might want to do to a real code base, like "switch to a different database engine" or "add user authenticaion". That's why it includes the qualification "real-world". The original article definitely does not fall into that category. > * A tutorial is what you decide a beginner needs to know. > * A how-to guide is an answer to a question that only a user with some experience could even formulate. That was some extra clarification from the linked article on the difference between tutorial and how-to guide. That makes it even more clear that the article is more like a tutorial than a how-to guide. > Tutorials are lessons that take the reader by the hand through a series of steps to complete a project of some kind. That's from the page about tutorials. The article introduces a reader to a substantial new topic from scratch and guides them through it, but it doesn't do so by making them complete a specific project, so it doesn't fit this definition. But that doesn't stop it from being a "tutorial". The requirement that tutorials have to involve completing a sample project is invented by the author of that page and not part of the usual definition of that word. This final point is pure conjecture, but I suspect the author of that page was just trying to strongly encourage people to base tutorials around sample projects. It's fair to encourage that, because often tutorials are improved by basing them around a single unifying project (but not always). But putting it in their definition of the word was a mistake, because that's not what that word means, and it's only created confusion.
ethanfinni 6y ago
Do you have a good JS tutorial for beginners that meets the definitions you are proposing to compare and contrast?

dboreham 6y ago

'And thirdly, the code is more what you'd call "guidelines" than actual rules.'

useragent86 6y ago

I looked at those links. Here's what I got from them: 1. Tutorials "are lessons that take the reader by the hand through a series of steps." They "are oriented towards learning how." 2. How-to guides "take the reader through steps." 3. "How-to guides are wholly distinct from tutorials." If I found a "community" around a topic, do I then get to decide what words mean? By consensus, of course.

xixixao 6y ago
You can see a good breakdown of what they mean by each label in this table: https://documentation.divio.com/introduction/#the-secret https://documentation.divio.com/introduction/#the-secret It's certainly a valuable take, even if you disagree with the claim that all 4 functions are required for good documentation.
- quietbritishjim 6y ago
  What specifically are you referring to in that table? The original article is a lesson on how to use JavaScript, from scratch, for a beginner. That perfectly fulfills all four requirements in the "tutorial" column: > oriented to: learning > must: allow the newcomer to get started > its form: a lesson > analogy: teaching a small child how to cook It does not satify all the requirements of any other column.

quietbritishjim 6y ago

This is a tutorial. It almost fits the definition of "tutorial" at the link you posted, but not quite, but that's because the definition at the link you posted is a bit flawed. It definitely is not a how-to guide, and the links you posted strongly support that. > How-to guides take the reader through the steps required to solve a real-world problem. That is from the linked article on how-to guide. By "real-world problem" it means something specific you might want to do to a real code base, like "switch to a different database engine" or "add user authenticaion". That's why it includes the qualification "real-world". The original article definitely does not fall into that category. > * A tutorial is what you decide a beginner needs to know. > * A how-to guide is an answer to a question that only a user with some experience could even formulate. That was some extra clarification from the linked article on the difference between tutorial and how-to guide. That makes it even more clear that the article is more like a tutorial than a how-to guide. > Tutorials are lessons that take the reader by the hand through a series of steps to complete a project of some kind. That's from the page about tutorials. The article introduces a reader to a substantial new topic from scratch and guides them through it, but it doesn't do so by making them complete a specific project, so it doesn't fit this definition. But that doesn't stop it from being a "tutorial". The requirement that tutorials have to involve completing a sample project is invented by the author of that page and not part of the usual definition of that word. This final point is pure conjecture, but I suspect the author of that page was just trying to strongly encourage people to base tutorials around sample projects. It's fair to encourage that, because often tutorials are improved by basing them around a single unifying project (but not always). But putting it in their definition of the word was a mistake, because that's not what that word means, and it's only created confusion.

ethanfinni 6y ago

Do you have a good JS tutorial for beginners that meets the definitions you are proposing to compare and contrast?