Helping improve the documentation of Python
July 12th, 2011 at 9:28 amAs I was reading this discussion on the drawbacks of Python, I was greatly surprised to see that a few answers, including the currently top-rated one, mentioned Python’s documentation as one of its weak sides.
I have always considered Python’s documentation to be excellent. I also know that a lot of effort is being invested in keeping Python’s documentation correct, useful and up-to-date. A sizable part of my own work as a Python core developer so far was focused on documentation.
To make this post constructive, I propose the following:
If you find some flaw in Python’s documentation, don’t just sit there fuming. The Python developers really care about documentation, and will gladly work towards making it better. You have a few options to influence:
- Open a documentation issue on the Python issue tracker.
- Send an email to the docs@python.org mailing list.
- Or just shout it out loud (in a blog, a forum, Stack Overflow, or wherever), hoping someone will pick it up.
You can also send me an email – I’ll be happy to discuss and re-route the report to the appropriate destination.
P.S. While in my Python work I focus on CPython – the official C implementation, documentation is one of those areas that can benefit all implementations of Python, since they all basically implement the same "language spec" (barring some slight differences such as the ones documented here). The CPython documentation serves as the formal description of the language and its standard library. So helping make the docs better will not only help CPython, but Jython, IronPython and PyPy as well.
Related posts:
July 12th, 2011 at 09:47
> since they all basically implement the same “language spec”
The PyPy’s compatibility webpage says that there’s no documentation for when a overhiden method of a subclass of a built-in get called.
http://pypy.readthedocs.org/en/latest/cpython_differences.html#subclasses-of-built-in-types
Before reading that I didn’t knew why some code I wrote wasn’t working…
July 12th, 2011 at 09:52
Bernardo,
Thanks, I’ve added a clarification to that sentence.
July 12th, 2011 at 10:43
I also think the search engine produces poor results.
Of course someone could just use Google but some kind of simple rating giving priority to title, label matches would be nice.
July 12th, 2011 at 15:00
The top rated answer has 20 votes, but it has the following comment with 19, which essentially negates the bullet point about documentation:
“Python docs are some of the best. Hands down better than Java.”
I too find it surprising that the OP says Java and PHP have better documentation. Can they type “help(almost_anything)” and get introspected documentation in Java or PHP?
July 12th, 2011 at 17:35
Python documentation is bad, compared to any other language besides C man pages. It’s not bad per se compared to e.g. average open source project documentation, but for a proramming language it’s not that great.
Most of the documentation (not all of it) is written by professionals for professionals – not for novices. Docs make the assumption that you know UNIX, underlying C architecture, system calls and so on. The docs assume that you have graduaded in CS and you have done your 101 of OS architectures and so on.
There are no cross references or see also: “you might actually want this function”.
Functions lack examples: if you look the page http://docs.python.org/library/os.path.html you see zero full code example. You can compare it to this http://php.net/manual/en/function.pathinfo.php as an example. PHP docs have much more novice friendly attitude.
I also believe that the documentation won’t be improved by call for arms. If you want to improve the documentation you must have a tool in the documentation itself to give feedback and improve it. This is not 80s and LaTeX anymore. People are used to Facebook Like button. Improving documentation should be as easy as pressing Like button.
I think the greatest near term thing what could happen for Python is that it would get PHP-like per function discussion board where people can post examples and ask for help.
A similar idea was proposed for Plone community, but the discussion ended like “let’s keep docs separate from the discussion as no one is able to answer the support calls or the docs would include off-topc discussion” (actually plone.org documentation section has its commenting disabled)
I think that’s shitty attidude.
Python docs would be the best place to let people share their worries and the best feedback channel to actually improve the documentation.
Some more ideas here:
http://blog.mfabrik.com/2011/03/29/when-python-sucks-how-you-call-a-function-and-document-it/
July 12th, 2011 at 17:42
… and even if you tried to improve documentation you need a different mindset to write documentation different people find useful. It takes practicing to see things from newcomer viewpoint (empathy and all, the skills engineers often lack).
I don’t claim the documentation is a hard task, but even if some hardcore Pythonist wanted to improve the documentation the result might not be beneficial for the great masses.
July 12th, 2011 at 19:54
The documentation available online is better than the documentation accessible via pydoc. My beef is that it’s harder to locate the page you want, compared to
pydoc module.function.I actually came here to complain about the links to http://docs.python.org/ that
pydoc moduledisplays in the “MODULE DOCS” section being broken, but today they all work for me. I wonder if that was a transient error on the python.org side. Or maybe I was just looking at the more obscure modules — try following the module doc link thatpydoc xml.etree.ElementTreegives you, for example.July 13th, 2011 at 06:00
The missing piece in the official documentation is one that sits in between the library reference and the language reference to explain to people how it *works* (and not in a language implementor focused way).
A version of this exists and has been contributed to the PSF (by me), but I need help getting it out of the ODF files and updated for current versions of Python: http://svn.python.org/view/sandbox/trunk/userref/
July 13th, 2011 at 06:30
On reading that page, I’m now wondering if the people griping about the poor docs haven’t looked at them since they were switched over to Sphinx in 2.6.
The gripes are significantly more valid when it comes to 2.5 and earlier (compare http://docs.python.org/release/2.5.4/ to the current docs)
July 13th, 2011 at 06:32
pydoc definitely has had its problems – it received a major update in 3.2, but that won’t help anyone still on 2.7.
July 13th, 2011 at 06:35
Marius,
Which version of
pydocare you talking about here?Also, if you find that links are incorrect this is surely a bug (which may be, as you noted, an intermittent connection/server error), so feel free to report it to the bugs tracker / mailing list.
July 13th, 2011 at 06:37
Nick,
I doubt there will be a lot of motivation to invest considerable effort into improving the documentation of 2.7 – perhaps better documentation should be one of the selling points of 3.x
July 13th, 2011 at 06:40
Mikko’s feedback regarding examples is exactly why some of us wanted to automatically include direct links to Python Module of the Week (http://www.doughellmann.com/PyMOTW/, aka “Python Standard Library By Example”) from the official docs. Let the official docs continue to serve as the library *reference*, but provide quick access to additional explanatory material.
I also recently discovered http://homepage.mac.com/s_lott/books/python/html/index.html as another potentially useful resource for potential Python programmers.
Rather than trying to do everything ourselves, we may want to try to do a better job of directing people towards resources that *we* think do a good job of introducing people to Python. We trust committers to actually make changes to the code and documentation, we should trust ourselves to recommend good web resources, too.
July 13th, 2011 at 06:42
jimd,
Can you be more specific? It would help if you could mention a few terms where you got bad search results.
Miko Othamaa,
You are raising some interesting points, but why the pessimism
? The Python community definitely wants the language to be welcoming to newbies (and in fact Python is widely acclaimed as on of the best languages to start programming with). However, there are of course tradeoffs to consider. For instance, how “dumbed down” and lengthy the docs should be is a tradeoff. After all, there are many great free books about Python out there that take care of this. The reference documentation should also cater to the more experienced devs, treating them with due respect, and not explaining trivial facts in minute detail.
That said, I repeat that I find your notes definitely worthy of consideration and I will consider raising some of them for discussion.
July 13th, 2011 at 06:47
Nick,
While PyMOTW is great, there’s a version problem. For instance, it now contains Python 2.x code. Can you link that from the 3.x docs? I don’t think so, because those newbies needing the examples will just get syntax errors which will make them even less pleased.
A alternative idea would be to selectively fold parts of PyMOTW into the documentation. I’m sure Doug will have no problems with it, and it shouldn’t take much effort since the information is already there.
July 15th, 2011 at 22:01
Eli:
I am pessimistic because I have been working with great Python developers for too long
I know their mindset and how hard it might be to change. But the starting point is admit the current state of affairs and if we need to do something.
Cheers