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!
|