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
--Larry Wall in <199911192358.PAA24109@kiev.wall.org>
Did I say I expect Perl to do the right thing? :-)
--Larry Wall in <199911200217.SAA24898@kiev.wall.org>
Stories, comments, journals, and other submissions on use Perl; are Copyright 1998-2006, their respective owners.
README et al (Score:2)
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.
Re:README et al (Score:2)
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
Reply to This
Parent