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:

https://documentation.divio.com/

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/GBPCAGDXYLZPKK3BH2MGSGTS3IO3CO5H/
Code of Conduct: http://python.org/psf/codeofconduct/