Previous Page
Next Page

7.3. Extended Boilerplates

Extend and customize your standard POD templates.

The two templates recommended in the previous section represent only the minimum amount of information that should be provided to the user. There are many more possibilities that your team might choose to add to its standard template, such as:


=head1 EXAMPLES

Many people learn better by example than by explanation, and most learn better by a combination of the two. Providing a /demo directory stocked with well-commented examples is an excellent idea, but your users might not have access to the original distribution, and the demos are unlikely to have been installed for them. Adding a few illustrative examples in the documentation itself can greatly increase the "learnability" of your code.


=head1 FREQUENTLY ASKED QUESTIONS

Incorporating a list of correct answers to common questions may seem like extra work (especially when it comes to maintaining that list), but in many cases it actually saves time. Frequently asked questions are frequently emailed questions, and you already have too much email to deal with. If you find yourself repeatedly answering the same question by email, in a newsgroup, on a web site, or in person, answer that question in your documentation as well. Not only is this likely to reduce the number of queries on that topic you subsequently receive, it also means that anyone who does ask you directly can simply be directed to read the fine manual.


=head1 COMMON USAGE MISTAKES

This section is really "Frequently Unasked Questions". With just about any kind of software, people inevitably misunderstand the same concepts and misuse the same components. By drawing attention to these common errors, explaining the misconceptions involved, and pointing out the correct alternatives, you can once again pre-empt a large amount of unproductive correspondence. Perl itself provides documentation of this kind, in the form of the perltrap manpage.


=head1 SEE ALSO

Often there will be other modules and applications that are possible alternatives to using your software. Or other documentation that would be of use to the users of your software. Or a journal article or book that explains the ideas on which the software is based. Listing those in a "See Also" section allows people to understand your software better and to find the best solution for their problem themselves, without asking you directly[*].

[*] By now you have no doubt detected the ulterior motive for providing more extensive user manuals and written advice. User documentation is all about not having to actually talk to users.


=head1 (DISCLAIMER OF) WARRANTY

This subsection is essential in any software that is likely to be used outside your own organization. It should be in a section separate from the "Copyright and Licence", and it should be drafted by a competent legal professional (so you have someone else to sue if someone sues you). If you're not part of a corporation and don't have your own attack lawyers, a useful starting point might be clauses 11 and 12 of the GNU Public License (http://www.gnu.org/copyleft/gpl.html)[].

[] However, the author is not a competent legal professional and this suggestion is offered for information purposes only and in no way constitutes legal advice. This recommendation is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.


=head1 ACKNOWLEDGEMENTS

Acknowledging any help you received in developing and improving your software is plain good manners. But expressing your appreciation isn't only courteous; it's also enlightened self-interest. Inevitably people will send you bug reports for your software. But what you'd much prefer them to send you are bug reports accompanied by working bug fixes. Publicly thanking those who have already done that in the past is a great way to remind people that patches are always welcome.

    Previous Page
    Next Page