Skip to content
Find file
140a0c0
Philip (flip) Kromer colophon
81 lines (60 sloc) 2.86 KB

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:

        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.

Jump to Line
Something went wrong with that request. Please try again.