Thomas Guest has a hilarious, yet serious post up about “Entertaining Documentation” - it’s a response to a comment made by a perl hacker about the “snore fest” of the python documentation.
I really enjoyed the post - and I think he’s correct:
I can see where he’s coming from, but I disagree. In my opinion the Python documentation is well-organised, accessible and accurate. The documentation for some modules may be rather thin, but that’s the strongest criticism I would make. I do struggle to single out an entertaining excerpt, though: the documentation aims to inform, and at that it does well.
While not exactly knocking the socks off in the hilarity department, I live off the python docs. Heck - I can’t wait for 2.6 and 3.0 to come out because there’s been a ton of work done on the docs. Some of Doug Hellmann’s PMOTW article examples have been rolled in to improve the docs.
I’m not suggesting that the docs have to “stay dry” - but my only criteria for good docs is that they’re accurate, communicate the capabilities of what you’re looking at and provide decent, real-world examples.
To that end - if you want to contribute more docs, please do! While the 2.6 and 3.0 code bases are in RC status, and changes are being done very carefully, the docs are still fair game for improvement. You can see the dev version of the docs here.
Of course, we could slip a few haikus and limericks into the docs - maybe that would make it “more better”.