Documentation suggestions

[Kent Johnson]

Steve Holden wrote:
> BartlebyScrivener wrote:
>> Now you are on a page with promising-looking links that all start with
>> "BeginnersGuide," but the first three are not warm welcomes, they are
>> housekeeping matters about where you can take courses or how to
>> download Python for people who don't know whether they want to or not
>> yet, or there's one that says "examples" which will take you to the
>> ActiveState Cookbook site so you can get really confused.

<snip many more valid criticisms>

> I think the Python community as a whole should take this on board as 
> fair criticism. It would be really nice if a total beginner did actually 
> see a usable path through the web to their first working Python program.

OK I'll bite. That Beginners Guide page has bugged me for a long time. 
It's a wiki page but it is marked as immutable so I can't change it. 
Here are some immediate suggestions:

- get rid of the 1-7 list at the top it is very confusing and does not 
present information in a useful form or order. All of these links except 
the help link appear in the body text in more useful form.

- Change the sentence "Read BeginnersGuide/Overview to learn the key 
points." to "Read BeginnersGuide/Overview to learn what makes Python 
special." Or maybe get rid of it completely - I'm not sure evangelism 
belongs on this page.

- Add a sentence at the end of the paragraph that starts, "Once you've 
read a tutorial" that says, "Many other resources are listed in 
BeginnersGuide/Help."

On the BeginnersGuide/NonProgrammers page, I agree, Guido's tutorial 
probably shouldn't be listed first even with the disclaimer. It goes way 
to fast for a beginner. Alan Gauld's tutorial is very popular on the 
tutor list, so is A Byte of Python (which is not listed on the 
NonProgrammers page). I would list them first. Or maybe take a vote on 
the tutor list for favorite beginner's tutorial.

That should help a little, maybe we won't confuse the newbies before 
they even get to an interpreter prompt.

Kent

PS I am aware of the usual SF bug report procedure for docs, does it 
apply to these pages? I don't know, they don't have the usual "About 
this document" link at the bottom. I'm happy to submit a patch if that 
will help. Otherwise I'm not sure what "the Python community as a whole 
[taking] this on board" should look like.