Entertaining Documentation
A Programmer’s first language
A recent enquiry on the ACCU mailing list asked which programming language would be most suitable for a beginner. The general response favoured Python. This should come as no surprise: elsewhere, Python’s benevolent dictator for life explains:
- how his funky title came about, and
- how (somewhat to his surprise) Python has become increasingly popular for teaching and as a first language.
Hang on though! Back on the mailing list Mike Small voiced his dissent and spoke up for Perl.
… I also think the online Perl documentation blows away the online Python docs. One I can read for entertainment. The other has just the bare facts and is dull, although not as bad as the run of the mill doxygen-type tool generated, fill in the required fields docs you get for mainstream stuff like Java or .NET.
Compare…
http://perldoc.perl.org/perlbot.html
… with …
http://docs.python.org/ref/types.html
(if that’s an unfair comparison someone feel free to find me an excerpt from the standard python docs that isn’t a complete snore-fest).
Should documentation entertain?
Well, this did surprise me, primarily because it seemed such an unusual charge. It’s hard — harder than generally acknowledged, I think — to write good documentation. In the case of a language reference manual or a standard library user guide, “good” would mean accurate, accessible and written as simply as possible. Surely entertainment value doesn’t get a look in?
What’s more, for a language up there with Perl and Python, many readers face text written by an author from a different culture and in a language which may not be their first. Irony and wit easily get mistranslated.
Most jokes in software and its documentation fall flat. If it’s hard to write clearly, it’s almost impossible to write clearly and entertainingly. Guido van Rossum may be a fan of Monty Python, but I imagine he’s happy leave the humour up to experts like Cleese et al.
Maybe.
On the other hand, even the driest reference in computer programming makes space for an amusing — and informative — limerick.
I happen to think the standard Python documentation is generally very good. I wouldn’t recommend Python as a language for learners if this wasn’t the case. But perhaps Mike Small has a point. The very best software writers can entertain and amuse as well as inform — Donald Knuth being the outstanding example. “The Art of Computer Programming” manages to be academic without being dry, a readable reference. Classics like Jon Bentley’s “Programming Pearls” and Abelson and Sussman’s “Structure and Interpretation of Computer Programs” also show what can be achieved. From what I’ve read of his, Larry Wall is up there too, and his wit and linguistic energy shine through Perl, even if he didn’t personally document all of it.
Unix sets the standard
We mustn’t equate “entertaining” with “funny”. The Unix documentation (available at terminal near you via man or info) is hardly a chuckle-fest, but its vigour and clarity make it a fine read. Although it never aims to amuse, sometimes its deadpan delivery makes me laugh. Here’s the BSD documentation for a handy but non-standard C string function:
Note that because strlcpy(3) is not defined in any standards, it should only be used when portability is not a concern.
Typing man gamma on a nearby Linux box generates the painfully funny story of the confusion surrounding the naming and usage of the Gamma function.
HISTORY
4.2BSD had a gamma() that computed ln(|Gamma(|x|)|), leaving the sign of Gamma(|x|) in the external integer signgam. In 4.3BSD the name was changed to lgamma(), and the man page promises
“At some time in the future the name gamma will be rehabilitated and used for the Gamma function”
This did indeed happen in 4.4BSD, where gamma() computes the Gamma function (with no effect on signgam). However, this came too late, and we now have tgamma(), the “true gamma” function.
CONFORMING TO
4.2BSD. Compatible with previous mistakes.
In the main, though, the Unix documentation is plain, understated and accurate. It sets the standard for written software reference documentation.
Maybe this is why Mike enjoys the Perl documentation? I’ve heard Perl described as “shell on steroids”; and while the Perl documentation does have the look and feel of a man page, there’s also something a bit more pumped up and manic about it.
Entertaining Python documentation
What about the standard Python documentation? Certainly, it aims for a friendly, informal tone. Here’s an excerpt from the tutorial introduction:
By the way, the language is named after the BBC show “Monty Python’s Flying Circus” and has nothing to do with nasty reptiles. Making references to Monty Python skits in documentation is not only allowed, it is encouraged!
Later, this same tutorial makes good on that promise, taking us through the subtleties of keyword arguments with reference to the famous dead parrot sketch.
Functions can also be called using keyword arguments of the form “keyword = value”. For instance, the following function:
def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'): print "-- This parrot wouldn't", action, print "if you put", voltage, "volts through it." print "-- Lovely plumage, the", type print "-- It's", state, "!"could be called in any of the following ways:
parrot(1000) parrot(action = 'VOOOOOM', voltage = 1000000) parrot('a thousand', state = 'pushing up the daisies') parrot('a million', 'bereft of life', 'jump')
Well, I guess it beats the weary employee database examples found in so many programming texts. Sadly, though, the parrot sketch has been repeated too often, and in this case the “snore-fest” epithet sticks.
Multimedia documentation
Mike talks explicitly about “online documentation”, and these days online (for programmers, at least) implies:
- a decent browser
- plenty of pixels
- a high bandwidth connection
- javascript
- excellent graphics
- a means to collaborate and contribute
These factors, in combination, enable some novel possibilities for documentation. Hyperlinks provide basic navigation; mix in folding documentation and search facilities, and readers quickly find what they’re looking for. There’s ample space for examples and comments, for contributions, for diagrams, for audio and video content. Why bother reading how to create a graphical user interface using wxPython, for example, when you can effectively look over someone’s shoulder while they walk through its features?
I said earlier that the Unix documentation set the standard for written documentation. If you’re reading at a terminal 40 rows deep and 72 columns wide, with limited font rendering and graphical capabilities, you couldn’t do better. If you have a larger screen and more than one monitor, maybe you can.
Ducking the challenge
Returning to Mike Small’s challenge:
… someone feel free to find me an excerpt from the standard python docs that isn’t a complete snore-fest.
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.
Looking further
If you’re prepared to venture away from docs.python.org, you’ll find the Python community is served by some talented and entertaining writers. I’ve mentioned the Python Cookbook before: the entire text can now be found online, but I recommend getting hold of hard-copy so you can sit down and read it from cover to cover — definite armchair material. Many programmers contributed recipes to the book but it’s pulled together by some skillful editing and by the fine essays which introduce each chapter.
Tim Peters introduces the chapter on Searching and Sorting and if you scratch at Python a little harder you’ll find plenty more written by him. Here are his notes on Python’s hybrid sort algorithm. Here’s the implementation. Enjoy!
Articles