in reply to Seeking Wisdom: proposed fix for a broken CPAN module

I must say that when the problem is fixing code that has been labeled "... a useless module that gives you your arguments without the first one if that's a class or object ...", then maybe you should simply concentrate on providing decent documentation. Right now the documentation for OOorNO is horribly lacking in instruction, examples, and has no selling points whatsoever. You should address (at least indirectly) the following questions: I am a CPAN author myself, the first thing i did before i posted my module was some RTFM'ing: Ovid hit the nail on the head in one of his use Perl; journal entries: "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." brian d foy's words are golden as well - you would be wise to read them.

Time to toot my own horn: i am proud of the documentation i wrote for DBIx::XHTML_Table, i invite you to peruse it and learn from it. The first page contain a Synopsis that shows how to quickly use the module. Next is a brief Description that together with the Synopsis answers all three questions that i presented above. After that is a lengthy break down of the API and how to use each method. Also, i created a home page for the module which includes a Tutorial and a Cookbook for doing various, specific tasks with the module.

Even though nobody really uses my module, at least it's well documented. I am glad i wasted many hours on that. :)

Hope this helps and welcome to the Monastery. :)

jeffa

L-LL-L--L-LL-L--L-LL-L--
-R--R-RR-R--R-RR-R--R-RR
B--B--B--B--B--B--B--B--
H---H---H---H---H---H---
(the triplet paradiddle with high-hat)
  • Comment on (jeffa) Re: Seeking Wisdom: proposed fix for a broken CPAN module

Replies are listed 'Best First'.
Re: (jeffa) Re: Seeking Wisdom: proposed fix for a broken CPAN module
by Tommy (Chaplain) on Dec 28, 2002 at 18:19 UTC

    Yes, this helps very much. I've been looking for a good POD example/template, as well as a Cookbook example/template. I've been somewhat impressed with those of CGI::Session. Sherzod is a good friend of mine. What I really am digging for is--

    Is this effort a step in the right direction? It's not all there yet, speaking of the documentation especially, so I appreciated your feedback on exactly what sections I need to be focusing on when I continue working on the POD today, even though the SYNOPSIS was a given. All your points were very helpful.

    Thanks again for your feedback

    Let the devine bless(jeffa)