On Thu, Apr 18, 2002 at 10:48:10AM -0500, Andy Lester wrote: > > You are the author, so you should know better, than me. > > Appart from the DESCRIPTION supplied by the Modules you > > could tell us > > I think that what Andreas is getting after is that the README should > provide a summary of what the module is and why one would want to use it, > and maybe the most basic of examples.
I understand why README files are useful to FTPers. Since I already endeavor to put that information into the module docs themselves, my basic problem is one of redundancy. The only extra information above and beyond what's in the module docs that I'd throw into a README or INSTALL would be any special installation instructions. Since 99% of the time this is just a parrot of the perlmodinstall man page I usually find it redundant and don't bother. Which is why I tried the mod2readme experiment. If you look at the README and INSTALL docs for Text::Metaphone those are all autogenerated from the module itself. It includes the NAME, SYNOPSIS, DESCRIPTION and AUTHOR sections of the docs along with basic installation instructions, a pointer to perlmodinstall and a note about any extras you might need. In Text::Metaphone's case it sees the XS and notes that you'll need a C compiler. I never took mod2readme beyond a proof of concept. -- Michael G. Schwern <[EMAIL PROTECTED]> http://www.pobox.com/~schwern/ Perl Quality Assurance <[EMAIL PROTECTED]> Kwalitee Is Job One conway: unit of mind expansion. One Conway == ~20 lines of Perl code found in $CPAN/authors/id/D/DC/DCONWAY, which gives the sensation of your brain being wrapped around a brick, with kiwi juice squeezed on top. -- Ziggy
