Social problems of Python doc [was Re: Python docs disappointing]

[David Lyon]

Since you're talking about documentation, which is a part of python,
don't you think you should be discussing it on python-dev ?

That's where discussions about the documentation should be held.

haha - I'm just curious to see how long it will for them to
shut the discussion down. 

Before you do that, you should clearly work out in your own mind
how you think things need to improve. It's not good enough just
saying this or that is bad without having specific ideas on what
needs to change.

Good luck fellow sinner and blasphemer...

How dare you suggest that things could be improved...


On Sun, 9 Aug 2009 20:04:43 -0700 (PDT), Xah Lee <xahlee at gmail.com> wrote:
> The prob with python docs is with the python priests.
> 
> there are frequent posts about python doc's poor quality, and some
> efforts to improve the doc (such as wiki or seggestions), about few
> times a year (in so much as i've seen), the typical response is
> pissing fight, with python priests to tell them not to start another
> wiki, or “you should apply in our church first and formulate a PEP
> proposal first or kindly donate or otherwise fuckoff”, and so on.
> 
> i've wrote several articles about this issue, total time spend on this
> is probably more than 2 months full-time work. See:
> 
> • Python Documentation Problems
>   http://xahlee.org/perl-python/python_doc_index.html
> 
> just about each article above generates a thread of flames.
> 
> I also have re-wrote the entire python regex doc in 2005:
> 
> • Pyhton Regex Documentation: String Pattern Matching
>   http://xahlee.org/perl-python/python_re-write/lib/module-re.html
> 
> there are some positive reviews, but most are drawn out by nay-sayers.
> 
> I often receive thank you emails for 2 particular articles, which are
> most frequently google searched as indicated by my weblog:
> 
> • Python Doc Problem Example: gzip
>   http://xahlee.org/perl-python/python_doc_gzip.html
> 
> • Python Doc Problem Example: sort()
>   http://xahlee.org/perl-python/python_doc_sort.html
> 
> • Sorting in Python and Perl
>   http://xahlee.org/perl-python/sort_list.html
> 
> See also:
> 
> • Language, Purity, Cult, and Deception
>   http://xahlee.org/UnixResource_dir/writ/lang_purity_cult_deception.html
> 
>   Xah
> ∑ http://xahlee.org/
> 
> ☄
> 
> On Jul 31, 1:10 pm, kj <no.em... at please.post> wrote:
>> I'm pretty new to Python, and I like a lot overall, but I find the
>> documentation for Python rather poor, overall.
>>
>> I'm sure that Python experts don't have this problem: they have
>> internalized some good ways to access the documentation, are
>> productive with it, and therefore have lost the ability to see why
>> the Python documentations is deficient for beginners.  This explains
>> why a suboptimal situation can persist like this: those who are
>> most able fix it are also the least able to perceive it.
>>
>> I've heard similar complaints from other experienced programmers
>> who are trying out Python for the first time: poor documentation.
>>
>> Here is an *entirely typical* example: on some Unix, try
>>
>> % pydoc urllib
>>
>> The displayed documentation mention the optional parameter "data"
>> in practically every function listed (a few dozen of them).  This
>> parameter is not documented *anywhere* on that page.  All that we
>> are told is that its default value is always None.
>>
>> I'm sure that I can find a full description of this parameter if
>> I fire up Google, and search online.  In fact, more likely than
>> not, I'll find far more documentation than I want.  But my point
>> is that a programmer should not need to do this.  The full
>> documentation should be readily accessible directly through a few
>> keystrokes.
>>
>> I would love to know how experienced Python programmers quickly
>> zero in on the Python documentation they need.
>>
>> TIA!
>>
>> kynn