Python could improve its documentation

Python’s documentation is confusing and frustrating. As great as the language is, their documentation could be a lot better. Not the content of their documentation, but the navigability and structure thereof.

If you compare Python’s documentation to PHP’s documentation, you would see why. PHP got everything in one place. One book so to speak. Python got it all over the show in different “books”. There is nothing wrong with this apart for the fact if you go into the Language Reference book, go to a section in this book, there is no link back to other books like the Library Reference. A couple of links somewhere on every page linking to the other books would work wonders. The module reference is awesome, but as soon as you go into a module’s reference page, you need to click the modules button at the top or bottom to get back to a list of all the modules. Why not simply have a list of modules down the side as a menu, much the same as that PHP does with its function references?

One really frustrating thing is there is no search on hand in the Python docs. PHP got a search box on every documentation page and nothing is faster than simply entering the search phrase if you need to check something on a specific function. Python’s search is powered by Google and very accurate and effective, but you have to go to a separate search page, which is like the rest of the navigation in the documentation, pretty unreachable once you’ve left the page.

Another “nice-to-have” which PHP does and that would be really handy in Python’s documentation is the user examples/comments. PHP’s documentation is not at all as complete as Python’s is, but that simple little feature that allows users to leave some examples or comments makes the world of difference.

This might be a bit pedantic and petty, but it would just make lives simpler if it was done better! Yes, there are workarounds for almost all of the above issues by opening arrays of new browser tabs/windows. For now, workarounds will have to do.

2 Comments to "Python could improve its documentation"

• Neil Blakey-Milner said: On 10/03/2007 at 10:03 am

  You should check out the new Python documentation at http://docs.python.org/dev/3.0/ - I think it solves some of your problems. The rest - well, talk to the Python docs people - it’s all done on mailing lists, and all the code is available for you to add features to as well.

  I must say I consult the Python documentation a lot less than I do/did the PHP documentation. For two simple reasons: 1) It’s easier to remember the parameters and ordering in Python, and 2) the Python stuff is all documented on your machine already, especially if you’re using IPython. Want to know what to pass to function “x.foo”, just type “x.foo?” in IPython. Want to see the source of function “x.foo” - just type “x.foo??” in IPython. Want to know how the heapq module works? “pydoc heapq” from the command line.

• Stii said: On 10/03/2007 at 4:00 pm

  Thanx Neil. You’re absolutely right. Version 3’s docs is exactly what I meant! The downside is that they would probably not make any drastic changes to Version 2.x documentation any time soon…

  Thank you for the IPython tip! I did not even know about it and will definitely check it out. So we learn…

Spit it out!

Filed in: PHP, Python by: Stii