READMEs

At the top level of each project, include a README file describing the project in terms a new user or contributor can understand.

Describe the purpose of the project.

Give a brief summary of the project's purpose. Too often, developers neglect to include a project description in the README, infecting users with fear, uncertainty, and doubt. The treatment is a few, plain English sentences.

Example:

# vcdetect - detect which version control software manages a file path

vcdetect identifies which version control program, if any, is managing a project directory.

Assumes version control data is stored on the file system in plain, unambiguous, per-project fashion. This precludes the ability to detect arcane and offbeat version control software such as cvsnt, svk, and vss.

Demonstrate example usages.

Show new users how to use your project. Command line programs should include a few example runs. Graphical programs should include a few screenshots.

Example:

# EXAMPLES

    $ vcdetect examples/larry/
    examples/larry/: hg

    $ vcdetect examples/moe/
    examples/moe/: svn

    $ vcdetect examples/curly/
    examples/curly/: cvs

    $ vcdetect examples/curly/README.md
    examples/curly/README.md: cvs

    $ vcdetect ~
    /Users/andrew: unknown

Detail depedencies.

If your project depends on any other software packages or configuration, link to or include instructions for setting these up.

Example:

# REQUIREMENTS

* [Ruby](https://www.ruby-lang.org/) 1.9+
* [Guard](http://guardgem.org/)

Example:

    $ curl -s https://get.rvm.io | bash
    $ rvm install 2.0 && rvm use 2.0
    $ bundle install

Detail build instructions.

Programming newbies may not know how to build, install, and run the project from source. Include basic instructions for a local build.

Example:

# BUILD

    $ mvn package
    $ rm -rf output/
    $ hadoop \
        jar \
        target/wordcount-0.0.0.jar \
        us.yellosoft.WordCount resources/ \
        output/

Keeping build documentation up to date also helps when configurint continuous integration; you will likely copy and paste the same steps into Jenkins or Travis CI.

Use Markdown format.

Documentation can be written in any format, but Markdown is the de facto standard for writing READMEs and other basic documentation:

• Markdown is better at rendering clickable hyperlinks and showing images than plain txt files.
• Markdown is easier to learn than HTML.
• Markdown is supported by many code hosts, including GitHub, GitLab, and BitBucket.

Modern code hosts automatically look for README.md files and render these as clickable HTML pages. In fact, this book is written in Markdown:

https://raw.githubusercontent.com/mcandre/elements-of-commit-style/master/readmes.md