The Best Practices make some suggestions on additional things to include in your POD, and suggest those items get listed in your general boilerplates to fill out. Some of the suggestions are interesting, but I’m not sure they belong in every POD ever.
I already think the templates given earlier are too verbose for many situations, and would rather see ways to be reminded of what sections exist instead of being forced to wade through them all and delete them every time I start a module. Making modules should be easy, not painful. It’s already hard enough to get engineers to organize their code.
That being said, some of the things listed in this section in the book are interesting, and to be reminded to include them is excellent. While I don’t know if they belong in every module, they may belong somewhere in every project.
EXAMPLES: Isn’t the “Examples” section what the already-hard-to-manage Synopsis is supposed to be?
FAQ: I don’t think the FAQ belongs in every module. Maybe in a POD for the project, and maybe on the web site or wiki. Depends on how the project is being organized and the context it is for.
COMMON USAGE MISTAKES: I like the note that this is “Frequently Unasked Questions” but I don’t want to put examples of how to do it wrong anywhere. I think that’s what’ll show up in the Internet search, and it will cause more questions than it asks.
SEE ALSO: I loved the original Unix man(1) pages, because they had fantastic cross-references. I learned Unix on a real Unix system where the manual pages were complete, cross-referenced, and included general background sections. The modern Linux man pages are a pale, pathetic imitation of this. (And GNU with their drive to put things in the hard-to-use and opaque info tool damaged this terribly. I wish they’d stop.) Whoops, rant over, sorry. I just with the linking and anchoring tools in POD were easier to work with and less cranky and verbose.
I just noticed a footnote in this section that raises my hackles a little too. “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.” This is a terrible reason to write documentation. This continues the poor belief that engineers are different than other people and shouldn’t have to deal with them. The reason to write documentation is to help those other people, so that they can get the most possible out of the program you’re working with. You’re trying to make their lives better by making sure they have the knowledge to understand and use the system, not to make your life better by getting them to leave you alone.