The sin of no documentation

The Perl community now has two vocal people who demand good documentation and say "if you don't write documentation you better not upload your code". It is the same theme as was raised in The responsibility of a CPAN developer.

I don't link to the these posts as that would be just crediting them. You can find the most recent ones on the IronMan perl blog aggregator.

They basically say "lack of documentation is a sin". 25 lashes.

Here is the thing.

Having good documentation is extremely important!

It is important as it makes the specific module more usable. It is important as it gets more respect from your peers. It is important for the Perl community as a whole as in the end the quality and the usability of Perl and the CPAN modules reflect on the whole community. If you would like to see more people using Perl and joining the Perl community, we have to have better documentation and better tutorials.

So if you are writing a CPAN module, please invest time in writing documentation. If you cannot, for whatever reason (e.g. lack of time) then try to find someone who would want to cooperate with you. That can be a nice way to get someone involved.

I think we know that the Perl community recognizes the importance of the documentation. The TPF even paid money to Dave Rolsky to write documentation for Moose.

BUT

It is not a requirement to have good documentation. If I had to make a choice, I'd rather have a well written module that has lots of tests and works but has no documentation; than a half written, broken module with lots of documentation.

Others might prefer a broken module with lots of documentation. People can have different preferences.

If I see a module with little or no documentation I can leave it. That's sad. If I really need it I can I invest time to figure out how to use it. Then I can write some examples and some simple docs and submit them to the author. Helping the next CPAN user with very little work.

Better yet, in many cases I can submit my patch via Github.

If not that, you can write a blog entry as Yanick Champoux did while taming Pod::Weaver.

Even too much documentation might be a problem. People like myself and apparently Wolfgang Kinkeldei like simpler examples. He did not complain (although that was not clear from my original comment in the Perl Weekly) he just wrote a blog entry with an example on how to use Test::DBIx::Class.

How Open Source and CPAN work?

One of the nice things about Open Source is that if there is a piece of software out there that needs improvement (e.g. documentation) many people can help. Distributing the work load to many, many people. Sure it would be better if all open source code was released bug free, feature complete and with lots of good documentation.

Till that happens what you can do is

1) Contribute to existing CPAN modules.

2) Encourage others to contribute.

3) Complain and vilify the authors.

I'd recommend 1 or 2.