Think about Loose Coupling | |
PerlMonks |
RE: The sad state of Perl documentationby Maclir (Curate) |
on Sep 14, 2000 at 04:29 UTC ( [id://32406]=note: print w/replies, xml ) | Need Help?? |
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.
In Section
Meditations
|
|