README-README: A Style Guide for README files

Contents

The README.md file and supporting documents should describe the following, in this order. If the file starts getting long, break it into pieces

• Project Titles as a level-1 heading

  • with descriptive tagline: I should be informed and intrigued. Examples:
    • “Sinatra is a DSL for quickly creating web applications in Ruby with minimal effort”
    • “Rails is a web-application framework that includes everything needed to create database-backed web applications according to the Model-View-Controller (MVC) pattern.”
    • “Resque (pronounced like “rescue”) is a Redis-backed library for creating background jobs, placing those jobs on multiple queues, and processing them later.”

• Overview

  • what it does
  • why you might want to use it, and why you might not

• Example Usage: a basic example. Nothing fancy – put rich examples in the detailed usage section

• Getting Started

  • installation & prerequisites
  • how to run examples and tests
    • include a Procfile to start any necessary servers or daemon processes
  • location of:
    • code
    • issue tracker
    • wiki
    • blog posts, screencasts, etc
    • compiled documentation (add the project to rdoc.info)
    • travis-ci results
    • mailing list

• Design Goals

  • lightweight or full-featured?
  • performance, flexibility, expressiveness?

• Detailed Usage

  • models and interface
  • examples
  • configuration
  • middleware or plugins
  • how it works

• Comparable Tools

• Developer info

  • Important Components
  • layout of internal code tree
  • Limitations and known issues
  • performance and benchmarking

• Colophon

  • Credits – everyone who has contributed code, libraries from which we’ve borrowed code.
  • Copyright and License – state the license type (typically “Apache 2.0” or “All Rights Reserved and Confidential”) and refer to the LICENSE.md file. Don’t paste the license contents in here.
  • How to contribute
  • References

Formatting

• Call the file README.md.

• Write in markdown format.

  • You should use triple backtick blocks for code, and supply a language prefix:

    ```ruby
    def hello(str)
      puts "hello #{str}!"
    end
    ```

• Do not wrap lines. In emacs, enable the longlines-mode to make your document word wrap intelligently.

Supporting Documentation

Besides a README.md, your repo should contain a CHANGELOG.md summarizing major code changes, a LICENSE.md describing the code’s license (typically Apache 2.0 for our open-source projects, All Rights Reserved for internal projects), and a notes/ directory that is a git submodule of the project’s wiki. See the style guide for repo organization for more details.