
On Tue, Nov 10, 2020 at 8:07 AM Mats Wichmann <mats@python.org> wrote:
On 11/9/20 12:46 PM, Mike Miller wrote:
On 2020-11-09 10:44, Simon Cross wrote:
That's quite subjective. Personally I prefer a more complete tutorial which explains many details so that I don't immediately run into fundamentals I don't understand when I start using what I've learned. K&R was very popular, so I don't think I'm alone in this.
Indeed. A common problem with a lot of platform documentation I've experienced is that tutorials are "fluff" for absolute beginners, complemented with terse, dense reference material for experts. There is too often very little in-between to get you to the intermediate level.
That's why the current tutorial is fantastic, imho. It doesn't skip the all-important middle part of the journey, and gets you to near-intermediate within a few hours if you've programed before.
Perhaps the first step is too high, however. How about a new Section 0: Absolute beginners guide, for those new to programming?
Just 2 cents' worth, the difficulty this discussion exposes is things In The Wrong Place (subjective), and maybe not all of the required places actually complete. I thought the following was a pretty good discussion of the overall problem of documenting a complex ecosystem:
Daniele Procido who is involved with Divio has shared this with us when we were planning a workgroup. It's excellent content and guidelines.
If people think that model is reasonable, we sort of have most of it - we have Reference; HowTos and Explanations (mixed together in https://docs.python.org/3/howto/index.html); and Tutorial. _Some_ people think the tutorial has too much stuff that belongs in the HowTos and Explanations buckets, and that's probably where things should be built up. e.g. @raymondh has been working on the Descriptor Howto, which is a good example of more detailed material not getting stuffed in the tutorial :)
I agree. I wouldn't suggest a major refactor of the existing tutorial right now (next 1-2 years). Instead, new beginner tutorial pages targeted at user groups (primary school students, scientists, web developers, etc.) would make sense to supplement the existing tutorial. I suspect that future documentation will have "How Tos" being more often written to cover more technical topics in detail. These more standalone "How Tos" can then be linked to from contents and search pages.
_______________________________________________ Python-Dev mailing list -- python-dev@python.org To unsubscribe send an email to python-dev-leave@python.org https://mail.python.org/mailman3/lists/python-dev.python.org/ Message archived at https://mail.python.org/archives/list/python-dev@python.org/message/GBPCAGDX... Code of Conduct: http://python.org/psf/codeofconduct/