Python docs disappointing - group effort to hire writers?

[r]

On Aug 10, 11:13 am, Ethan Furman <et... at stoneleaf.us> wrote:
(snip)
> As someone who relies heavily on the docs I will also say that the idea
> of giving the ability to modify the official documentation to somebody
> who is /learning/ the language is, quite frankly, terrifying.
(snip)

Ethan,
I think what you and a few others seem to miss is ... Of course nobody
wants Joe-Noob writing the Python docs -- thats lunacy, would you give
your 12 year old the keys to a shiny new corvette? -- No! What people
are asking for is the ability for a noobs input on the official docs,
and for that input to be taken seriously. Sure some of the suggestions
will be nothing more than "helpful ignoramuses" with unhelpful
suggestions as some have said, but the input channels need to be
there. Currently Python dev seems to be more output than input,
however i could be wrong? We some real I/O going on here.

Also the Python tut is full of fluff (sorry Guido) and it contributes
to late learning of the language. Luckily however Python has many
users who really love the language and have taken the time to write
beautiful tutorials that start at various levels of entry. Read xah's
take on the official tutorial, it's spot on baby!

A little note for tutorial writers:
==================================

Dear Expert,
Whilst writing any tutorial on any subject matter please remember, you
may be an expert, but mostly *non-experts* will be reading your
material... pssft, this may come as a surprise, but tutorials are
meant for *NON-EXPERTS*!

Please refrain from stroking your own ego by obstrufcation of the very
ideas you wish to convey to these influential minds. Sure exposing
your huge intelligence to the world may give you warm-fuzzies-in-your-
tummy, but believe me your poor students will be rendered as helpless
as Paris Hilton at a "panties required" spelling bee.

Please try, and i know this is a lot to ask, to use the most simple
explanation to convey the point -- and *only* the point at hand! Take
for example the introduction of functions. You could go with your gut
instinct, "shoot from the hip" and pop off something like this that
prints a Fibonacci series up to n...

def fib(n):
    a, b = 0, 1
    while b < n:
        print b,
        a, b = b, a+b

>>> fib(2000)
1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597

And all you would have accomplished was to blow holes thru the
students mind! Now like the next guy, i love calculating series of
numbers all day, but this is a piss poor example of functions for the
new student, or anybody for that matter!  While your student is
racking his brain trying to figure out what "a" and "b" stand for,
much less n, and not to mention what the heck a "Fibonacci" series is
in the first place (Google can help though) , he (the student) has
forgotten that this example is simply how to write and call a
function. A much better example would be the following...

def add(x, y):
    print x+y

>>> add(1, 2)
3

WOW,  with that small piece of code you have just transported three
main principals of a function in a very simple and strait forward way
smack-dab into the cerebral cortex of the student, and your fingers
did not even break a sweat!

 1. function names should describe exactly what they do
 2. functions take arguments
 3. functions do something with those arguments(like mini programs!)

You could followup with this fine example that extents on the
first...

def add(x, y=2)
    return x+y

>>> add(1,2)

>>> print add(1, 2)
3
>>> print add(1)
3
>>> print add(100, 5.5)
100.5
>>> print add()
error...


However Ethan (and Co.),  not everybody who downloads Python the first
time knows about this. Also the Python website is filled to the brim
with a hodgepodge of "links-here" "links-there", "links-every-freaking-
where" (are we getting paid by the link people?) causing most noobs
brain to start blowing chunks just while tring to find a good
alternative to the official tut!

Really, it's bloat on a proportion that only elephant sized bloat
wares like M$, M$-Office, Adobe-PDF, and the like, can hold a candle
to. Python really needs and enema, and thats no joke!