This isn't a shout at anyone, just a 'isn't that interesting' note. No deep philosophy here.

I've used a lot of Open Source stuff, and I've noticed something that may be a trend - most (there'll always be an exception) successful development tools have superb documentation. Checking our favourite programming language, I notice that it is dripping with documentation that is nothing short of superb.

It helps a lot that Perl has a built-in document markup language, but that's only the start. The thing that makes it rock is that most people use it. In particular, they provide examples. In no other documentation have I seen so many good examples that I use to get me started. I'll practise what I preach and give an example - CGI.pm. The following code starts on the eleventh line of the documentation, so obviously someone wanted it to be seen.

# CGI script that creates a fill-out form
# and echoes back its values.

  use CGI qw/:standard/;
  print header,
        start_html('A Simple Example'),
        h1('A Simple Example'),
        start_form,
        "What's your name? ",textfield('name'),p,
        "What's the combination?", p,
[download]

Look at that. You hardly even have to write your own code. Just edit what's in the docs. Long before I knew what an object really was, I was cutting and pasting the following from the same document:

#!/usr/local/bin/perl -w
   use CGI;                             # load CGI routines
   $q = new CGI;                        # create new CGI object
   print $q->header,                    # create the HTTP header
[download]

In theory cutting and pasting is wrong, but in reality it's only wrong if you cut and paste bad code. Suzuki claims that "Look, try, learn" is the better way to learn things, and it worked for me. I started wondering what the new was doing, what the arrow was... I started learning.

The above code snippet could easily have been covered by a few words of text, like "Create a new instance of the CGI class and then call the header method to output a valid HTML header, see the appendix for the arguements to the method". But that would have been useless to me. I would have had to roll my own because I couldn't understand the instructions.

I ran across this problem myself trying to do GUI with Perl. Tk looks ugly to me so I thought I'd give GTK a go (very easy on the eyes). The documentation consisted of one basic tutorial and then the instruction "Go read the C library reference (ick!) for more information". Back to Tk, with it's lavish documentation and - you guessed it - examples.

Sometimes module authors provide code examples of how you might use their code functions in your program. This is great. I want to encourage people to go overboard on their documentation if there's any chance of someone else reading it. That way one day Perl might get a rep as the best documented code or something really kinky like that.

After having all these thoughts I went back through and did up all the documentation in my code. It now looks so attractive people may find themselves compelled to read it. I'm currently mulling over the idea of providing some kind of 'narrative' that will be in POD but also fill the role of commenting the code. Kind of like the literate programming I've seen, only not quite.

____________________
Jeremy
I didn't believe in evil until I dated it.