21 Mar 2005 fxn   » (Master)

Pragmatic Documentation

One of the things I miss when I am programming in something that is not Perl is pragmatic library documentation accompanying specifications, architecure descriptions, or whatever you want to put there. I don't understand why you are supposed to infer the usage of some library from the spec so often in Java, C, Python, etc. From my experience, in general the Perl conventions are ahead of any other I know.

When you read the documentation of a Perl module you see:

  1. How the module is used
  2. The module specification

The first part is code, right there, no English. By convention it goes in a section called SYNOPSIS which is the first one you see after the one-line description and the table of contents. See for instance the SYNOPSIS of IO::All. You get the picture at a glance. Not the details, to know the details or get the complete interface you then read what you need below, but you already have context.

To give a recent example of lack of pragmatism, look at the most recent documentation of the standard Python module CGIHTTPServer. Oh man, how on earth do I set up a server with that class? One reads that page and thinks: Hum, well, let's try the docs of its parent class. Ha, not so easy dude! Have a look at SimpleHTTPServer. Nope, you find a similar page. OK, be patient, maybe we'll have more luck with the documentation of BaseHTTPServer? Now something! At last! Some example!

But now, how to translate that example to CGIHTTPServer? You backtrack the links and try to figure it out. Finally you come to produce:

    import BaseHTTPServer
    import CGIHTTPServer
 
    handler_class = CGIHTTPServer.CGIHTTPRequestHandler
    server_address = ('', 8080)
    httpd = BaseHTTPServer.HTTPServer(server_address, handler_class)
    try:
        httpd.serve_forever()
    except KeyboardInterrupt:
        pass
which curiously enough does not instantiate a CGIHTTPServer. Shrug.

Latest blog entries     Older blog entries

New Advogato Features

New HTML Parser: The long-awaited libxml2 based HTML parser code is live. It needs further work but already handles most markup better than the original parser.

Keep up with the latest Advogato features by reading the Advogato status blog.

If you're a C programmer with some spare time, take a look at the mod_virgule project page and help us with one of the tasks on the ToDo list!