Skip to end of metadata
Comment: add another example link
Go to start of metadata

Each clojure-contrib project has a README. This file should contain:

  • Instructions for including the library as a dependency in Maven / Leiningen
  • Links to the library's pages on Hudson and JIRA
  • Links to the available releases on Maven Central and oss.sonatype.org
  • Link to generated API documentation, if available
  • General usage instructions (should mention which namespace to use/require)
  • Developer Information: links to GitHub project, Bug Tracker, Continuous Integration, Compatibility Test Matrix
  • Change log of all releases (may also be in separate file)

Example READMEs: tools.reader, data.json

Labels:
None
Edit Labels

2 Comments

Hide/Show Comments

  1. Jan 03, 2012

    Fogus

    I would love to see an example of the ideal README.

  2. Jan 16, 2012

    Rasmus Svensson

    *inc*

    I added the "should mention which namespace to use/require". "Which namespace should I use/require to utilize library X?" is a common question in the IRC and many library READMEs actually forget to mention this.

    In my view an ideal README should at minimum have these (the first two as close to the top as possible):

    1. Dependency group/artifact/version triple
    2. Link to API documentation
    3. If there are code examples in the README, they should begin with a ns/use/require line

    This is what a developer needs to know if he/she already knows that the library exists, what it does, and just wants to get started using it.