Re^2: Our documentation sucks

[jimt]

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!

print "Content-type:text/html\n\n";

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

        print header;

             -or-

        print header('image/gif');

             -or-

        print header('text/html','204 No response');

             -or-

        print header(-type=>'image/gif',
                             -nph=>1,
                             -status=>'402 Payment required',
                             -expires=>'+3d',
                             -cookie=>$cookie,
                             -charset=>'utf-7',
                             -attachment=>'foo.gif',
                             -Cost=>'$2.00');

Good docs, props to Lincoln. But, to the new user, it doesn't work. If I go back to my code and type in:

use CGI;
print header;

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:

Content-Type: text/html; charset=ISO-8859-1

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.

[GrandFather]

That's odd. When I wrote my first CGI script using CGI I copy and pasted the synopsis sample, edited it a little and it worked straight off. It may be because the first couple of "interesting" lines in the sample are:

  use CGI qw/:standard/;
  print header,

which, without reading the comprehensive documentation, DWIM. Hey, maybe some of this CPAN documentation isn't so bad after all. ;)

[perrin]

You know, there's plenty of things to criticize about CGI.pm, but the docs are not one of them. It has an excellent synopsis section. Many people essentially learned CGI programming from the CGI.pm docs.

And look at your header example: you didn't know that adding the charset to the end helps prevent cross-site scripting attacks, but CGI.pm did, and if you had used it you would have gotten the benefit of that knowledge for free.

[chromatic]

"It doesn't work,", you say? "Baloney," I reply. It works just fine for me.

Are you sure it works? I'm pretty sure it violates the relevant RFC for HTTP headers, and thus Postel's law.

Check your line endings.

[itub]

It may not be the cleanest, but it certainly works fine if you are using Apache, because it munges the headers anyway.

[chromatic]

I know you and many other people know that, but without actually knowing the details of your platform or the RFCs, how does anyone know that? Assuming that things just work is often a mistake, and I see people make it often.

It's fine to build a better wheel, but only if you've done your research.