Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

Ovid (2709)

Ovid
  (email not shown publicly)
http://publius-ovidius.livejournal.com/
AOL IM: ovidperl (Add Buddy, Send Message)

Stuff with the Perl Foundation. A couple of patches in the Perl core. A few CPAN modules. That about sums it up.

Journal of Ovid (2709)

Monday October 28, 2002
02:32 PM

Bad docs

[ #8646 ]

I'm not going to name the module because I don't want to slam the author, but I'm reinventing a CPAN wheel. My boss, in looking at some of my code, knew the module that I was ignoring and asked me why.

"Because I can't understand the documentation."

The module actually looks like it would be useful, but try as I might, the docs may as well be written in Klingon. I suspect that the module actually does far more than I need as the interface in some of the examples is very complicated, so I could use the "leaner, meaner version" argument. But I still can't understand the docs. If you're going to write a CPAN module, don't skimp on the documentation. If I can't understand it, I probably won't use it.


List all Journal entries
The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.

Bad docs 13 Comments More | Login | Reply /

 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • Name that module!

    My vote for bad module of the day is Ananke::Template [cpan.org] which is just a bad imitation of TT.

    • But that's not the only bad imitation of TT. Look at HTML::KTemplate [cpan.org] as well. Like most of the worst of TT mixed with HTML::Template. Ick.
      --
      • Randal L. Schwartz
      • Stonehenge
      • Ick. The only thing worse than inventing the wheel is doing it badly.

        I may have to start scouring the depths of CPAN for a "bad module of the week". This may help the Schwartz factor a bit :)

        • It would probably be nice to give the authors a chance
          to clean up their module before announcing their shame.

          Otherwise you'll just become loathed =)
          --
            ---ict / Spoon
        • Along these lines, I nominate Text::Macros. It has documentation more or less sufficient for what it does, but what it does is crummy. I think the author released it (four versions!) without ever bothering to finish it.

    • No can do. The module itself appears to be useful and some checking around reveals that others are using it (though not very widely). If it was a bad module, I don't mind calling a spade a spade. I just want to be sure that I'm being decent and not trashing a good module just because someone didn't do a good job of communicating. Let's face it, programmers who write great code are often known for being less than diligent about their docs :)

      Amusingly, I found a tutorial for using this module that was e

      • I don't feel too bad about rewriting it (it only took me about 3 hours)

        Yeah, the great thing about Perl is how easy it is to write stuff. I think that is an important reason for the success of CPAN -- it is easy to add stuff, because it's easy to write in the first place! Syntax *is* important (take that, lisp fans)!
      • Is this, by any chance, NetAddr::IP?

        Not being a native english speaker, and having a tutorial online at The Perl Monastery [perlmonks.org], it would not surprise me.

        If it is indeed one of my modules, I would want to know.

        Regards.

        -lem

        --

        -lem [cantv.net]

    • Hi, Yeah, is one imitation of TT, but, Ananke::Template use only 200k of memory and TT use 2M, imagine 100 modperl using with persistent connection... Anake::Template is very very very speedy and small. Now i have other module, NTS::Template (Ananke::Template rewrite), is more stable, speedy and use less memory... but documentation is bad my english is bad ;) bye
  • A lot of people's model of writing a module is to work on a module until they're absolutely sick of it, and then they're just about to release it, and they think "ugh, I guess I'd better write some docs". Not a great frame of mind to be in for writing docs.
    • I am not the very model of a modern extreme programmer, but I try to document the API was I go, and that is most of the battle right there. I should probably write tests too, but, well, I, um, have to go eat dinner ...
  • I'm notorious for having bad docs for my modules, so I wouldn't be entirely surprised if it was one of my modules you were talking about (and I wouldn't be offended either :-)

    But you should contact the author. He might have just dropped the ball a bit, and would be more willing to get started again if he got feedback that someone wanted to use his code.
Stories, comments, journals, and other submissions on use Perl; are Copyright 1998-2006, their respective owners.