Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • I don't like having information spread over all the different files, so I am tending more and more to put all documentation in well-named and well-placed sections in the Pod. I just generate the README that.

    Since I say the Pod must always start with why you should use the module, that makes for a relevent README.

    This approach also simplifies things for makepmdist and its users.

    • That makes sense, too. The main thing is, I hate looking at a module, thinking, "What does that do?" and then reading installation instructions or licensing info in the README.  :) Secondarily, I hate looking for something in the place where I expect it (Changes, for example) and not finding it, and having to search through three other files to find out where s/he put it.

      So a relaxed generalization of my preferences is, "Put what I want in the place where I expect it. Other stuff is cool, if it's short pointers ("at the bottom of this file") or ("see file FILENAME for further info"), or down at the bottom so that I see what I'm expecting at the top.

      The POD should start with why you should use the module. Vigorous agreement from me. To me the README is an abstract, and if you did a good job of the POD, I think the first few paragraphs of it should suffice for that abstract.

      Another thing I saw after I wrote the rant: don't start the "DESCRIPTION" section of the POD with bugs or missing features! How can I know it's a bug or missing feature when I don't even know what the module does yet?  :)

      --
      J. David works really hard, has a passion for writing good software, and knows many of the world's best Perl programmers