Python documentation annoyance

March 13th, 2009 at 6:09 pm

Edit: I’ve actually started working on fixing this annoyance in Python. See Python issue 9264.

Edit 2: my patches to the documentation were all committed and issue 9264 has been closed. No more annoyance :-)

I love Python, but the documentation of its standard library (or the lack thereof) is sometimes annoying. Python’s “batteries included” approach is good, but sometimes modules get into the library without proper quality assurance. And quality is not only the correct workings of the code, but also the level of its documentation.

For example, today I wanted to use the trace module. The Python 2.5.2 documentation installed on my workstation has very scarce documentation, so I thought that it has perhaps been fixed in 2.6, but alas, no.

The documentation of the programming interface of trace is minimal, and most important options aren’t documented at all. The single existing example is trivial and definitely inadequate for understanding what the module can do.

So, once again I go to the Python installation and read the module’s code. Luckily Python is the most readable programming language one can think of, so the module’s code can be easily understood. But this, naturally, isn’t the right way to do it.

Related posts:

  1. Helping improve the documentation of Python
  2. Contributing to Python
  3. How Python affected my C/C++ brace style
  4. Python development – improving ElementTree for 3.3
  5. Book review: “Rapid GUI Programming with Python and Qt” by Mark Summerfield

12 Responses to “Python documentation annoyance”

  1. ulrikNo Gravatar Says:

    In python3.0, try help(zip) — it sounds like that’s just the itertools.izip help text, it wasn’t adapted for builtin status. And that’s a pretty big doc failure on **builtin** functions.

  2. Robert BrewerNo Gravatar Says:
    But this, naturally, isn’t the right way to do it.

    Why not?

  3. elibenNo Gravatar Says:

    @Robert,

    Does it seem logical to you to insert a module into the standard library of Python and supply no documentation except the source code itself?

    When I want to use a module, I’m looking for documentation of options and examples of common usage. I don’t want to wade through the code to see what can be done – this is hardly a good way to provide an API.

  4. David GoodgerNo Gravatar Says:

    Now that you’ve answered your own question (by using the source), how about editing the docs & submitting a patch? Python is open source, and is the sum total of what people put into it. If you don’t, who will?

    But you knew that.

  5. ChristofNo Gravatar Says:

    Also you can try to find a PMOTW column, for trace it is here: http://blog.doughellmann.com/2008/10/pymotw-trace.html

    Adding to the Python docs as David Goodger suggested would be preferable though (I don’t know David personally, but he always seems kinda offensive, does he not? But maybe it is just me ;)

  6. Kay SchluehrNo Gravatar Says:

    Now that you’ve answered your own question (by using the source), how about editing the docs & submitting a patch?

    That’s good idea. I give someone else my half-baked code and everyone who wants to use it is called to read my intentions and write some piece of documentation. That’s how open source should be: collaborative on a very fine grained level. Everyone who even remotely cares rewards the programming genius by spending at least an hour to fix a few minor bugs and tries to understand what everything means.

    Another equally viable suggestion might be to ask Xah Lee instead of discussing to ban him. It’s some sort or re-socialization. Xah Lee once took care for documenting parts of the stdlib and linked the results in one of his rants. They were far superior than most of the stuff we are used to read. So why not offer him a PSF grant?

  7. Tim ParkinNo Gravatar Says:

    I have to agree with the posters suggesting contributing some small amount of documentation. Python doc editing used to be difficicult, now it is very easy.

    Even if you only add a few notes, it’s probably better than nothing (as you have found). You don’t even need to write your doc contris in restructured text..

    Go on.. you know you want to .. people will think better of you if you do and I’ve heard it also makes you more attractive to the opposite sex (that may be a lie propogated by the PSF though)…

  8. Peter NooneNo Gravatar Says:

    I’ll chime in to agree with DG and his sentiment regarding OSS and contributions. I don’t know if he’s offensive in general, but his comment here certainly isn’t.

  9. Kay SchluehrNo Gravatar Says:

    I’ll chime in to agree with DG and his sentiment regarding OSS and contributions.

    It’s surely a nice idea and since there are so many do-gooders here and elsewhere who subscribe to grassroot socialism I expect to see the official Python docs going for perfection within the next few months. Then we can all agree on the base of results and not sentiments.

  10. AnonNo Gravatar Says:

    I can’t tell if Kay S. is joking or not.

    I think it’s a bad bad idea for programmers to throw (albeit working) code over the wall and then expect others to comb through it looking for clues on how to use it and then write up their findings to be used as documentation for said code.

  11. seiska tarjousNo Gravatar Says:

    Ha I think the lack of documentation is problem with every other software modules or libraries I have used. I don’t even write documentation but I sure make some inline documentation with the code so that I can remember it better when I have to fix it someday.

  12. JoeNo Gravatar Says:

    Try Doug Hellmann’s site before looking at Python’s docs http://www.doughellmann.com/PyMOTW/trace/index.html#module-trace

Leave a Reply

To post code with preserved formatting, enclose it in `backticks` (even multiple lines)