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

[dn]

On 18/07/20 11:48 PM, Oscar Benjamin wrote:
> 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.

>>> 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/
...

> 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.
...

+1, well written!


For grins (as boB would say) I scanned Oracle's intro pages to Java 
programming (JDK), and they have a logical progression from installation 
instructions to "proving" the installation with the ubiquitous 
Hello-World first-program.

Whereas the MySQL web site requires one to select the appropriate 
download and then remember (!) to keep reading. Whereupon the manual 
offers advice about testing the server, etc.

Whereas those are decades old and well-established, in case of 
comparison the 'younger' MongoDB's documentation was more complicated. 
The installation of the server was not followed by a link to information 
about running the client, to be able to assure the system and understand 
the most basic (debugging?) linkage.


None of these are suited to the 'smart phone' world, where software is 
selected from an 'app store' and once installed, 'it just works'. Is 
that where these neophyte users' troubles start - a disconnect between 
such expectations and the Python reality?
(it's all very alien to my Linux world/memories of MS-Win .msi files 
with a check-box at the end which invited a start-up or display of 
suitable help files)

Yes, the observation that we have folk who are quite probably 
downloading a command-line program(me) for the first time in their 
lives, but is that a valid excuse?


What I've run out of time to compare-and-contrast is the advantage of 
pointing users at a Python-environment distribution, eg Anaconda. If 
'we' are less interested in caring for beginners and their basic needs, 
should we point them at others who are?


Observations (further to/underlining @Oscar's points):

- the requirements of a beginner installing for the first time (and 
maybe his/her first programming language) are totally different to 
someone wanting to install a new version of Python or on a new machine. 
(ie done-it-all-before/want it to be quick-and-easy/don't bother me with 
loads of docs)

- most docs seem to try to be 'all things to all people', whereas the 
differences between platforms inevitably make the writing complicated 
and the reading difficult to follow. Thus, consider separating entries 
by OpSys and/or installation method.

- a reference manual is not 'the place' for beginners, who require a 
more tutorial/hand-holding approach

- a beginners' installation tutorial should include a first program(me) 
and thus run through the command-line/editor/execute/REPL etc 
philosophies. This may be opening yet another 'door', given the range of 
editors (I don't think that Idle is part of the Python download for all 
OpSys, any more)...
-- 
Regards =dn