Choose Your Own Tutorial
Writing Zilla-Enhanced Documentation
Documentation Boilerplate Eradication
The CPAN has good community standards for documentation. The Pod documentation format makes it pretty easy to write documentation, too. The big problem is all the boring boilerplate that you're expected to write. Take this hypothetical document:
So, in the above fifty lines or so, only about ten are specific to the package or interesting to maintain. Distribution "starter" tools can set this boilerplate up, but it's still up to you to maintain it, but that's a drag. With the right configuration, Dist::Zilla will let you replace the above documentation with:
Now, the only documentation you've written is the documentation you care about. Everything else gets written only as needed, and it's added each time you release, so it always uses the latest version of your preferred layout and configuration. This is done by Pod::Weaver.
To get most of the benefit of Pod::Weaver, just add this line to your dist.ini:
This will add sections for each module's name, abstract, version, authors, license, and a bunch of other bits in the middle like the synopsis and methods. It will let you use the commands
=func to set up self-organizing sections for methods, attributes, and functions.
For the short-form list syntax shown above, you'll need to bring in another Pod::Weaver plugin. One way is to drop a weaver.ini file in your dist directory and put this in it:
That sets up all the default plugins as well as a plugin for Pod::Elemental::Transformer::List.
Pod::Weaver can't work with your module if you have Pod in string literals.