Yes, the documentation for File::Find would be improved a great deal if it were to actually mention (or even, *gasp*, explain) the basic concept of what the module does. ;)

It never says, for example:

For each directory you specify, File::Find calls a function that you provide (&wanted) for each file and directory found in that directory, every subdirectory, every subsubdirectory, etc., allowing you to "do something" for each file/directory within an entire directory tree. To use File::Find, you have to write a function that, each time it gets called, will decide what should be done with a specific file [for example, based on whether it is an ordinary file (-f $_) or if the file name matches some pattern (/\.html?$/i)] and then perform those operation(s). [...]

It mearly says that "it traverses a directory tree" and that you pass it a "wanted" function and talks about various details. It never actually says that "wanted" is called once for each file, much less explain the concept.

This is rather sad as File::Find is part of the base distribution. Many modules don't enjoy this level of attention and so are often just the ramblings of a lone hacker trying to offer something useful to the community. The lone hacker may not have great language skills (especially in English which might be "a second language") or have other reasons why the documentation doesn't really shine.

So modules are a very mixed bag. If you find one that has documentation that gives you a hard time, the best thing that you can do is to get the documentation updated. The most important step in that process is finding someone motivated enough to actually produce and submit a patch to the module maintainer and then follow-up if needed. I suggest you look to yourself for that.

Then you need to get someone to write some decent documentation. Perhaps just asking about the module here and requesting specific suggestions for documentation updates could get you the raw material for producing a patch.

But reading documentation should not be a struggle, especially for someone who says they include RTFM-ing as part of their normal problem resolution.

If Perl's documentation style is such that is inherently difficult to understand, then I would posit that it needs to be changed. Note that this isn't a knock on Perldoc, which is more of a document definition. Rather, perhaps it's a knock on Perl documentation style. Structure versus content and all that. All modules should, in their documentation, have a clear and complete documentation of the interfaces present in the module. This may be all c is needing.

Documentation style is a balance between what people find easy to read, and what authors are going to actually write. While it would be nice for beginners if people wrote customized tutorials that explained material in perltoot in every module, that realistically is not going to happen. And besides which, experienced Perl programmers won't want to spend time wading through a recitation of standard material.

The style popular in Perl is one from Unix. It is terse, accurate, and to the point. Because it is terse, it is easy for a module writer to follow the style and actually document their complete module. So they do. Were it more verbose, it would be harder to write hence less often written, and harder to audit for errors, and therefore would be less accurate.

But if you want to get a book, well you are going to have to buy it. Because that is not the way that POD is used, and people are generally not going to go out and verbosely document just for fun...