A Python installation help doc much more friendly to newcomers? [Was Re: help]

[Oscar Benjamin]

On Sat, 18 Jul 2020 at 05:39, dn via Python-list <python-list at python.org> wrote:
>
> On 18/07/20 3:29 PM, boB Stepp wrote:
> > On Fri, Jul 17, 2020 at 9:48 PM dn via Python-list
> > <python-list at python.org> wrote:
> >>
> >> On 18/07/20 1:53 PM, Castillo, Herbert S wrote:
> >>> I downloaded python not to long ago, and today when I opened Python on Windows it gave me a modify setup prompt. I have tried to click on modify , repair and even uninstalled and installed it back, but when I try to open Python up again, I keep on getting the same modify setup prompt. I am not sure of what to do? Thank you in advance.
> >>
> >>
> >> Regret that this mailing list does not support graphics attachments.
> >>
> >> Which part of https://docs.python.org/dev/using/windows.html failed?
> >
> > Just for grins I just now glanced at the link dn provided.  Yes, this
> > is a very thorough, very accurate, very *technical* help resource.
> > But if I were a person who had never seen a shell, cmd.exe or
> > Powershell window, never programmed before, had no clue about how to
> > truly use my OS, etc., I don't think I would understand a bit of this
> > "help" document, and, at best, would find it very intimidating.  If
> > this community does wish to cater to those who are totally new to the
> > world of programming and learning how to really use their PC at any
> > depth, then I think a different approach or set of documents is
> > needed.  And an easier way for those playing with the idea of learning
> > programming and Python to connect with such documentation.
> >
[snip]
>
> There is also THE Python Tutorial - the opening action is two?three
> pages 'in'. Is that suitably less-technical and more usable to a 'beginner'?
> https://docs.python.org/3/tutorial/index.html

I would say that the official tutorial is not targeted at the total
novice. I think it used to be described as the tutorial for people
with experience of programming in other languages but I might be
misremembering.

The main python.org page links to a "beginners guide" well actually
there are two beginners guides...
https://www.python.org/

Under "get started" there is a link to this beginners guide:
https://www.python.org/about/gettingstarted/

You can also hover over documentation and choose beginners guide to
get this one:
https://wiki.python.org/moin/BeginnersGuide

The former starts by asking whether you are new to programming and if
so suggests this page:
https://wiki.python.org/moin/BeginnersGuide/NonProgrammers

It also has an "installing" section which links to here:
https://wiki.python.org/moin/BeginnersGuide/Download

All of these have lots of information and many links to other pages.
I'm not sure how you'd find the page dn linked to which is at least
more direct about how to install:
https://docs.python.org/dev/using/windows.html

Certainly I don't see it if I go straight to the download pages:
https://www.python.org/downloads/
https://www.python.org/downloads/windows/

I think if I was new to programming or installing software in general
I would find all of this quite bewildering.

My experience of teaching total novice programmers is that you really
can't shirk the fundamental question: how should I install this thing
and start using it *before* I have any idea what I'm doing? Novices
don't need to be told that there are 100 ways to do it: they need to
be told exactly how to do it in a way that will work for them.

If I was writing the tutorial but aiming at total novices I would
probably begin by suggesting to use an online shell:
https://www.python.org/shell/

There could be a short guide there that explains very clearly how to
do simple commands in that online shell. At that point you are ready
to test the examples from page 3 of the official tutorial but I think
it is still not pitched at novices:
https://docs.python.org/3/tutorial/introduction.html

Then after a few examples and some familiarity it could be time to
suggest installing locally. That should be with a no nonsense
explanation that makes no reference to terminals, PATH, etc because
those are just intimidating distractions to a novice at that point in
time.

The sympy docs have a lot of room for improvement but one of the
things that is very useful for beginners there is the "Run code block
in sympy live" button which means that you can follow the
tutorial/docs and try things out before having anything installed
locally:
https://docs.sympy.org/latest/tutorial/intro.html#introduction

--
Oscar