in reply to Our documentation sucks

I don't think the need is for Yet Another Documentation Protocol, but simply for better and more consistent use of the current protocol. I heartily agree that an example that does exactly what I want so I can cut and paste it is ideal, but how does the module author know what nefarious purpose I may may find for his wonderful module?

It's not the format of the documentation that is the problem, it is the documentation itself. Not everyone can write good documentation just like not everyone can write good code. And just because someone can write good code doesn't mean that they can document it well. All the rules and format changes you like are not going to get someone who is incapable of writing good documentation to write good documentation, or even provide comprehensive and comprehendable examples.

There are some excellent examples of good documentation on CPAN (MIME::Lite for example) and many examples of poor documentation and quite a few examples where the problem domain is so big that no documentation is ever going to address everyone's needs (XML::Twig comes to mind).

At the end of the day this just isn't a fixable problem, unless of course you are volunteering for the job? :)

DWIM is Perl's answer to Gödel

Replies are listed 'Best First'.
Re^2: Our documentation sucks
by xdg (Monsignor) on Apr 13, 2007 at 07:25 UTC
    Not everyone can write good documentation just like not everyone can write good code. And just because someone can write good code doesn't mean that they can document it well.

    ++ just for that quote!

    I don't think the need is for Yet Another Documentation Protocol, but simply for better and more consistent use of the current protocol.

    I agree. Personally, I think the synopsis ought to show at least some cases, not be a dumb list of how the constructor works and what methods can be called.

    More generally, I think the standard is for people write cookbooks that give more in depth use-cases.

    Of course, it helps if the main Pod mentions that a cookbook exists, too.

    -xdg

    Code written by xdg and posted on PerlMonks is public domain. It is provided as is with no warranties, express or implied, of any kind. Posted code may not have been tested. Use of posted code is at your own risk.

[reply]
Re^2: Our documentation sucks
by naikonta (Curate) on Apr 13, 2007 at 02:34 UTC
    At the end of the day this just isn't a fixable problem, unless of course you are volunteering for the job? :)

    I believe that AnnoCPAN isn't there for nothing :-)

[reply]
Re^2: Our documentation sucks
by jimt (Chaplain) on Apr 12, 2007 at 23:11 UTC

    I'm less concerned with some new protocol or format or something than just better docs. But that was my idealized example.

    As for the nefarious purpose argument, I look at that as a future use thing. I want better docs so most users get their foot in the door, not so experienced hackers bend the module to their will. Get people using the module, then they'll try to worry about how to enhance it in the future.

    Most of the good use cases up front, something that can be cut 'n pasted, and that'll take care of most things. By all means include the docs to hack it like crazy afterwards, but most docs seem to skew towards that at the expense of the n00bs.

[reply]

In Section Meditations