|Think about Loose Coupling|
Re^2: Our documentation sucksby jimt (Chaplain)
|on Apr 12, 2007 at 23:27 UTC||Need Help??|
No amount or quality of documentation will fix the line of thinking that, for example, "It's a good idea to print HTTP or CGI headers directly, even if they're likely malformed and incorrect, because CGI.pm must be big and bloated and slow."
I disagree. Here, how do I print out an HTML header? Easy!
"It doesn't work,", you say? "Baloney," I reply. It works just fine for me. Why should I go learn some module and download and import it just to duplicate what I did in one line? Especially when I need to root through the docs. It doesn't affect you, it's not your code, and it works just fine. Why do I need a module?
Now, I'm playing devil's advocate. I use CGI.pm, don't get me wrong, but I don't remember how to print out a header without looking it up. I use it buried deep inside a black box so I never actually see the call to the header routine.
A quick glance at the docs yields a pretty decent section -
Good docs, props to Lincoln. But, to the new user, it doesn't work. If I go back to my code and type in:
Nothing happens. Yes, yes, strict tells me about the bareword, and maybe I know enough to try guess to import the header function into my namespace (use CGI qw(header)) to make it work, but maybe I don't. A quick grep in CGI's docs found that "CREATING A STANDARD HTTP HEADER:", but it didn't explicitly tell me to import the function.
The case can be made that it's just being lazy ("Go read all the documentation!"), but it's still a barrier to entry. One line to print it out by myself or round trips to the docs to find out how to do it, then to find out that I need to import another function. Maybe I should've just looked at the synopsis and tried importing :standard, but maybe I didn't know that. If the example block started off with "use CGI qw/:standard/", I would've been going immediately, and arguably be happier to use the module.
When I finally get it working, I see that my output is:
I could've just printed that out myself, right? Why wasn't I told to just add on the charset=ISO-8859-1 bit to my manual print line? Instead I was sent to a new module to read documentation in multiple places to get something that I see no benefit in?
Yes, this example's quite contrived since it's so simple.
But I stand by my premise - if the docs have quick, easy to find, complete, and correct examples, people are going to be more likely to use 'em. Point them in the right direction for the module, and they can get up and running immediately instead of trying to learn something additional.
And before people start claiming I'm against learning modules, I'm not. I just want people to get up and running with a module in the minimal case as fast as they can. Then they can learn additional features once they've solved the immediate problem at hand.