Russ Allbery wrote:
What about combining AUTHOR with the sections ACKNOWLEDGMENTS, CREDITS, and CONTRIBUTORS? These and AUTHOR have the shared purpose of identifying who contributed to the software, either by actual coding and design or just by providing feedback, patches, or "moral support." In fact, AUTHOR is not well named because there can be multiple authors and many types of contributors besides authors. Therefore, CONTRIBUTORS seems most appropriate for encompassing all of these Note that contributing to software does not necessarily provide someone legal rights to it. As I've suggested, anything with legal weight (e.g. copyright) might go in some type of LEGAL section....but yes, generally, AUTHOR does look odd to me. It just doesn't have anything that it can reasonably be combined with, except maybe the copyright information (which wouldn't make it much longer).
So, here's how I see the sections outlined, where each main section addresses precisely one major question or concern.
NAME - name + one line description identifying the module
SYNOPSIS - quick introductory examples _that precede_ the description
DESCRIPTION - details on what the module does and lists functions
LIMITATIONS (or BUGS, CAVEATS, RESTRICTIONS, TODO) - limitations of the module: what's broken, what can be be improved, common mistakes, whether the module is stable or experimental (e.g. interface subject to change)
CONTRIBUTORS (or AUTHOR, CREDITS) - contributors, people to thank. AUTHOR seems appropriate only if the module is the work of largely one person. This may overlap pod2man's HISTORY section a bit if the contributions of the contributors are given. I.e. where did the ideas come from? (e.g. prior art)
LEGAL (or LICENSE) - things with legal weight, i.e. for the lawyers to read and contemplate over
SEE ALSO - like a bibliography, providing links to resources mentioned in the previous sections.
The above sections are not perfect and do not address these other main questions:
- Where can I obtain support? e.g. technical questions, provide feedback, submit bug reports and patches. Does the module have a project web site (e.g. on sourceforge)? and specifically....
- Where can the software be obtained? or downloaded from? what about development snapshots and CVS copies? This might be the AVAILABILITY section mentioned in perlpodtut II.
- Has the interface ever changed? What changes affect compatibility? How are version numbers assigned? What provisions or guarantees are made for future changes to the module interface?
- What other modules or components does the software depend on? Are there any OS or hardware requirements? (if any). Maybe these are LIMITATIONS.
- Where are detailed and practical examples? E.g. like a tutorial or software cookbook showing solutions to common scenarios...things beyond the straightforward DESCRIPTION of the module.
-david
