Giters

zcei / standard-readme

:star2: README Standard Style — One Style to Rule Them All

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

learn from CPAN

hackergrrl opened this issue · comments

commented

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)