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: https://documentation.divio.com/ 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 :)