Documentation suggestions

[Steve Holden]

BartlebyScrivener wrote:
> You are correct about the tutorial. Just try to look at the home page
> through the eyes of a curious Windows user who wants to learn
> programming and is trying to decide whether to take up Perl, Ruby,
> Python, or Visual Basic, let's say.
> 
> On the home page, the first link that catches the eye for this user is:
> "Beginner's Guide to Programming - <bold> start here if you're new to
> programming </bold>." That's me. Click.
> 
> 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.
> 
> Then you hit the link that says "BeginnersGuide/Nonprogrammers" Ah!
> That's me. <click>
> 
> The first prominent link says: "Python Tutorial" along with a notice at
> the top of the page that tells you if you've never programmed before
> this is the page for you.
> 
> Click on Python Tutorial. Some official business to start off. Then you
> see, "Whetting Your Appetite" Ah, I am ready for that. <click>
> 
> The first sentence reads:
> 
> "If you ever wrote a large shell script, you probably know this
> feeling: you'd love to add yet another feature, but it's already so
> slow, and so big, and so complicated; or the feature involves a system
> call or other function that is only accessible from C ...Usually the
> problem at hand isn't serious enough to warrant rewriting the script in
> C; perhaps the problem requires variable-length strings or other data
> types (like sorted lists of file names) that are easy in the shell but
> lots of work to implement in C, or perhaps you're not sufficiently
> familiar with C."
> 
> Most of the site has been laid out by programmers, for programmers, who
> apparently want to keep it that way, based upon what I've seen.
> 
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.

regards
  Steve
-- 
Steve Holden       +44 150 684 7255  +1 800 494 3119
Holden Web LLC                     www.holdenweb.com
PyCon TX 2006                  www.python.org/pycon/