[Python-Dev] Python Doc problems

Josiah Carlson jcarlson at uci.edu
Thu Sep 28 19:40:24 CEST 2006

xah lee <xah at xahlee.org> wrote:
> There are a lot reports on the lousy state of python docs. I'm not  
> much in the python community so i don't know what the developers are  
> doing anything about it.

I don't know about everyone else, but when I recieve comments like "the
docs are lousy, fix them", it is more than a bit difficult to know where
to start, and/or what would be better.

Case-by-case examples of "the phrasing of the docs here is confusing"
are helpful, as are actual documentation patches (even plain text is
fine).  While I have heard comments along the lines of "the docs could
be better", I've never heard the claim that the Python docs are "lousy".

> anyway, i've rewrote the Python's RE module documentation, at:
>   http://xahlee.org/perl-python/python_re-write/lib/module-re.html
> and have recently made the term of user clear.

Aside from a few sections in the original docs, and also some sections
in your docs, about the only part of the original docs that I find
unclear is that some sections do not have function names sorted
lexically.  This is confusing compared to other module documentation
available in the stdlib.

I would also like to make one comment about your updated docs (I didn't
read them all, I'm on vacation); In the section about 'Regex Functions'
you used r'\w+@\w+\.com' as a regular expression for an email address in
information about the search() function. This particular RE will only
give results for the simplest of email addresses. I understand that you
wanted to provide an example, but providing a generally broken example
will be detrimental to newer Python RE users, especially those who were
looking for a regular expression for email addresses.  I would say slim
it down to domain names, but even the correct RE for domain names (with
or without internationalization) is ugly.  I don't currently have an
idea of what kind of example would be simple and illustrative, but maybe
someone else has an idea.

> may i ask what the python developers is doing about the python's  
> docs? Are you guys aware, that there are rampant criticisms of python  
> docs and many diverse tries by various individuals to rewrite the doc  
> by starting another wiki or site?

If there are "rampant criticisms" of the Python docs, then those that
are complaining should take specific examples of their complaints to the
sourceforge bug tracker and submit documentation patches for the
relevant sections.  And personally, I've not noticed that criticisms of
the Python docs are "rampant", but maybe there is some "I hate Python
docs" newsgroup or mailing list that I'm not subscribed to.

While I personally think that having a wiki attached to the
documentation is a decent idea, I fear that we would run into a
situation like php, where the documentation is so atrocious that users
need to comment on basically every function in every package to
understand what the heck is going on.

 - Josiah

More information about the Python-Dev mailing list