learn from CPAN

[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)