Documentation suggestions
Kent Johnson
kent at kentsjohnson.com
Wed Dec 7 12:10:18 EST 2005
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.
More information about the Python-list
mailing list