RE: The sad state of Perl documentation

[Maclir]

Generally, there are two types of documentation:

1) Stuff that tells you how to do things. This assumes that you know what you want to do in the first place ("Hmmm - is the recurse option on chmod -R or -r?"). We call these "reference manuals" - the Camel book is a fine example of such a beast.

2) Stuff that tells you what things to do. This means you have an understanding of the end result that is needed, but not sure of the way to do it. The "Perl Cookbook" is a fine example of such a manual. These are far more useful for use beginning programmers.

But - much of perl's power lies in the great array of modules that are constantly being developed. The documentation of these varies from wonderful to woeful. But, what is missing is an extension of the 'how to' approach to incorporate these modules. For example, how many of the questions posed here are answered by:

You should use module Foo::Bar::WDNNS_Documentation

Now maybe that is what more attention needs to be focussed on. There are lots of resources on the web - merlyn's Web techniques column is one that immediately comes to mind. At least the experts here can regularly point us to such sources.

[SuperCruncher]

But - much of perl's power lies in the great array of modules that are constantly being developed. The documentation of these varies from wonderful to woeful.
True, but I am unhappy with the standard documentation, not the documentation for other modules. There's no way to force authors of modules to write documentation (except for maybe not putting them into CPAN unless they are accompanied by documentation, but I don't think this would be a good thing), and I'm not too worried about that, but I think that the basic core of the language should be well documented.

[mirod]

I will have to completely disagree here.

Perl itself comes with a huge amount of docs. I am sure it's harder to find your ways around it that let's say a CD player, but that's only because using Perl is a little more complicated than using a CD player.

And I am really unhappy with the sad state of the documentation for all VCR's I have ever owned by the way ;--)

I think enough people care about, and work on the core docs that it is quite comprehensive.</p

The problem is really with modules, as most of the time they are written, supported and documented by te same poor guy, usually better at (and more interested in) writing code than docs.

Plus the author is not necessarily the best person to write an introduction to a complex module. Things that seem easy and natural for someone who has written socket handling software for 10 tears might not be quite as natural to Joe Poor Perl Hacker who was writing COBOL up until last month.

So I think one of the best ways for module users to give feedback to the author is probably to write a piece on how they used the module, or just give some feedback on the doc.

I was documenting religiously and in great detail every single method in XML::Twig, until I realized through a random email on a mailing list stating that a potential user had given up after the first 2 screens (out of 22!). I needed to write a tutorial introducing the basics of the module (but more complex than the usual simple synopsis). Darn! But I'm really glad I caught that feedback. I hate coding stuff that will never be used because nobody looking for an easy way to solve a simple problem did not make it to the 44th method in the 3rd class of the module which was exactly what they needed.

So really I whished module docs were better and I think feedback could really help. But I'm happy with the core docs, thank you.

And stop killing trees and use perldoc, man and grep!

[SuperCruncher]

I will have to completely disagree here.
Ok, but can I make it clear that I have a few minor problems with the docs for some of the functions in perlfunc, and I think that the documentation should be available in more formats. That's all!

And I am really unhappy with the sad state of the documentation for all VCR's I have ever owned by the way ;--)
You know, VCRs etc are often cited as devices which are really difficult to use, etc. I did an HCI module last term and they were continually cited as being hard to use. I have owned 2 VCRs, and have never found them very complicated to operate or use. The docs provided explained the more "advanced" features (like timer or VideoPlus recording), and the rest was easy even without going to the documentation. One problem I have had thought is the counter-intuitive arrangement of buttons on the remote, but heck, you can't have it all, can you?

...and work on the core docs that it is quite comprehensive...
The docs are certainly comprehensive. I just think that in some areas they omit some information which would be useful to newbies and aren't quite as clear as they could be.