On Tue, Nov 10, 2020 at 8:07 AM Mats Wichmann <m...@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-le...@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/
>
_______________________________________________
Python-Dev mailing list -- python-dev@python.org
To unsubscribe send an email to python-dev-le...@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/SN3AVFNFVNNR3DWB7EE432OAM6P7TTPS/
Code of Conduct: http://python.org/psf/codeofconduct/

Reply via email to