learn from CPAN perl hackers

[hackergrrl]

Perl hackers have been writing great READMEs in a consistent format for ages: http://search.cpan.org/~lloydg/List-Zip-0.04/lib/List/Zip.pm

Key elements:

1. Name + Tagline: a tiny sentence that describes what the module does.
2. A "Description" section that gives people without necessary background the means to understand the module's purpose.
3. A concrete, runnable example that the user can copy locally and experiment with.
4. A Methods listing that documents the public API, complete with examples where it helps.
5. See Also: a mechanism for discovering other modules that work great with this one. (audio-lab does a great job with this throughout their audio modules)
6. Copyright / License (I'm more interested in the latter)

[RichardLitt]

Thanks! This is great.

[RichardLitt]

Thanks! Worked some of these in. I think they are perl specific, sometimes, and I want to keep this as general as possible.

[hackergrrl]

Here are a few tidbits that are pretty general but extremely spot on:

from perlmodstyle:

The level of detail in Perl module documentation generally goes from
less detailed to more detailed. Your SYNOPSIS section should
contain a minimal example of use (perhaps as little as one line of
code; skip the unusual use cases or anything not needed by most
users); the DESCRIPTION should describe your module in broad terms,
generally in just a few paragraphs; more detail of the module's
routines or methods, lengthy code examples, or other in-depth
material should be given in subsequent sections.

Ideally, someone who's slightly familiar with your module should be
able to refresh their memory without hitting "page down". As your
reader continues through the document, they should receive a
progressively greater amount of knowledge.

from http://mathforum.org/ken/perl_modules.html#document:

Your documentation is complete when someone can use your module without ever
having to look at its code. This is very important. This makes it possible for
you to separate your module's documented interface from its internal
implementation (guts). This is good because it means that you are free to
change the module's internals as long as the interface remains the same.

Remember: the documentation, not the code, defines what a module does.

[RichardLitt]

I should merge these thoughts in with a reasoning for each section in the spec. Reopening to remind myself to.

[hackergrrl]

Can we credit both? (Ken Williams is the author of the first quote btw)

[RichardLitt]

yes!