Python documentation annoyance
March 13th, 2009 at 6:09 pmEdit: 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:
March 13th, 2009 at 19:26
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.
March 13th, 2009 at 19:45
Why not?
March 13th, 2009 at 20:02
@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.
March 13th, 2009 at 21:48
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.
March 13th, 2009 at 22:51
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
March 14th, 2009 at 06:57
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?
March 14th, 2009 at 11:37
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)…
March 16th, 2009 at 21:52
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.
March 20th, 2009 at 08:19
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.
March 28th, 2009 at 23:56
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.
September 11th, 2009 at 21:51
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.
January 14th, 2011 at 19:25
Try Doug Hellmann’s site before looking at Python’s docs http://www.doughellmann.com/PyMOTW/trace/index.html#module-trace