[Python-Dev] Python Doc problems (original) (raw)

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/pythonre-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.

More information about the Python-Dev mailing list