Beefy Boxes and Bandwidth Generously Provided by pair Networks
Pathologically Eclectic Rubbish Lister

Re: More comprehensive style guide for Perl docs than perlpodstyle?

by eyepopslikeamosquito (Chancellor)
on Jan 07, 2019 at 06:26 UTC ( #1228125=note: print w/replies, xml ) Need Help??

in reply to More comprehensive style guide for Perl docs than perlpodstyle?

Though Perl Best Practices has a chapter dedicated to Documentation, I doubt it has the specific details you're seeking. Still, you might find some useful general tips there and in Ten Essential Development Practices, also written by Damian Conway (e.g. see practice "3. Create Standard POD Templates for Modules and Applications").

Further general advice on writing documentation for CPAN modules can be found in Writing Solid CPAN Modules, for example:

  • Separate user versus maintainer documentation. Tutorial and Reference; Examples and Cookbook; Maintainer; How your module is different to similar ones; Change log; Notes re portability, configuration & environment, performance, dependencies, bugs, limits, caveats, diagnostics, bug reporting.
  • Error Handling. Document all errors in the user's dialect.
  • Are there nicely commented tests covering the examples in the documentation? This acts as tutorial material for someone browsing the test suite and ensures the examples given in the documentation actually work.
  • Use Pod::Coverage to verify that your module's documentation is complete/comprehensive.

  • Comment on Re: More comprehensive style guide for Perl docs than perlpodstyle?

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://1228125]
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others examining the Monastery: (9)
As of 2020-05-28 08:13 GMT
Find Nodes?
    Voting Booth?
    If programming languages were movie genres, Perl would be:

    Results (165 votes). Check out past polls.