4 ms·
I think it's easy to get hung up on the terms. Take "tutorial", what's the definition of a tutorial exactly, when actual examples of things called "tutorials" d
by codeflo 3y ago
I think it's easy to get hung up on the terms. Take "tutorial", what's the definition of a tutorial exactly, when actual examples of things called "tutorials" differ so wildly?
I find this table helpful to understand the four types model: https://diataxis.fr/compass/ https://diataxis.fr/compass/
This makes two distinctions: step-by-step vs. knowledge, and studying vs. working. The names given to each of the four categories are not the main point in my opinion.
If we accept that categorization, then the offical Python tutorial is in the knowledge/studying quadrant IMO, so actually not a "tutorial", but an "explanation"! Which makes complete sense to me, you need an explanation to work with a programming language, and actually defangs most of the criticism in the article. See for yourself, it's not step-by-step at all, instead, you get very small code examples among a sea of explanatory text: https://docs.python.org/3/tutorial/ https://docs.python.org/3/tutorial/
So, yeah, words are used differently by different people.
- kaycebasques 3y agoCan we all take a moment to appreciate the irony that the technical writing industry has a huge problem with name overloading :D I get your categorization and agree with it but honestly... the world would be a much better place if we could collectively be more consistent with the labeling of our docs: * Users would find the docs they need faster because they know that the content of the "tutorial" really does line up with the usual definition of tutorial. * We would make more progress on documentation innovation because we would spend less time clarifying miscommunications like this. It's not going to happen, of course, but a man can dream