Beefy Boxes and Bandwidth Generously Provided by pair Networks
Pathologically Eclectic Rubbish Lister

use documentation;

by jepri (Parson)
on Jul 14, 2001 at 20:51 UTC ( [id://96751] : perlmeditation . print w/replies, xml ) Need Help??

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 - 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,

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

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.

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

Replies are listed 'Best First'.
Re (tilly) 1: use documentation;
by tilly (Archbishop) on Jul 14, 2001 at 22:20 UTC
    Widely used open-source software sprouts documentation for the same reason that active newsgroups sprout FAQs. In Larry Wall's words:
    laziness: ...and document what you wrote so you don't have to answer so many questions about it. Hence, the first great virtue of a programmer. Also, hence, this book...
Re: use documentation;
by nysus (Parson) on Jul 15, 2001 at 02:01 UTC
    Jeremy, I liked your post and I agree with you about the need for great documentation. I think a lot of documentation is geared toward people who are already in the know. Even with a well-documented language like Perl (which is my first programming lanuage), most of the battle was learning the jargon. At first, looking at a perldoc was like reading ancient Klingon. Programmers tend to write for the programming audience. Thankfully, there are some great books and documents that helped me out tremendously. It still took a lot of work but I can at least read most of perldoc now and understand it.

    I often wonder why programmers fail to dumb down their documentation. I would hazard it's easier for them to write at a more abstract level. It takes a tremendous amount of work to put yourself in the place of a newer programmer and write about the world from his/her perspective. Also, perhaps because they have been trained to think in compact ways, programmer authors are frequently too concise. Just about every sentence they write is packed with information with very little "storytelling" behind it. Instead of spreading an important idea over 3 or 4 pages like a novelist might, programmers tend to pack that kind of idea into 2 or 3 sentences.

    Though inaccurate in quite a few places, I think Learn (Baby) Perl in 21 Days was one of the best programming books I ever read. The writing style/approach to teaching Perl was just the book for someone like me who was unfamiliar with all but the most basic programming techniques. The author takes a narrative approach and was careful to cutback on the jargon and gently introduced new jargon when necessary.

    Anyway, keep writing the thorough documentation. To be more concise about all this: I think it's much better to be too wordy then too brief. Sure the veterans won't find it as enjoyable to read, but many newer programmers will be deeply appreciative. Please keep them in mind when your write.

    $PM = "Perl Monk's";
    $MCF = "Most Clueless Friar Abbot Bishop";
    $nysus = $PM . $MCF;
    Click here if you love Perl Monks