jessenoller.com

Thomas Guest has a hilar­i­ous, yet seri­ous post up about “Enter­tain­ing Doc­u­men­ta­tion” — it’s a response to a com­ment made by a perl hacker about the “snore fest” of the python documentation.

I really enjoyed the post — and I think he’s cor­rect:

I can see where he’s com­ing from, but I dis­agree. In my opin­ion the Python doc­u­men­ta­tion is well-organised, acces­si­ble and accu­rate. The doc­u­men­ta­tion for some mod­ules may be rather thin, but that’s the strongest crit­i­cism I would make. I do strug­gle to sin­gle out an enter­tain­ing excerpt, though: the doc­u­men­ta­tion aims to inform, and at that it does well.

While not exactly knock­ing the socks off in the hilar­ity depart­ment, 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 arti­cle exam­ples have been rolled in to improve the docs.

I’m not sug­gest­ing that the docs have to “stay dry” — but my only cri­te­ria for good docs is that they’re accu­rate, com­mu­ni­cate the capa­bil­i­ties of what you’re look­ing at and pro­vide decent, real-world examples.

To that end — if you want to con­tribute more docs, please do! While the 2.6 and 3.0 code bases are in RC sta­tus, and changes are being done very care­fully, the docs are still fair game for improve­ment. You can see the dev ver­sion of the docs here.

Of course, we could slip a few haikus and lim­er­icks into the docs — maybe that would make it “more better”.

Thomas Guest has a hilar­i­ous, yet seri­ous post up about “Enter­tain­ing Doc­u­men­ta­tion” — it’s a response to a com­ment made by a perl hacker about the “snore fest” of the...