roachhd/roachhd.github.io

---
layout: inner
title: "README Style Guide"
---
<section class="content about">

<!--  <h1 class="big thin">README</h1> -->
  
<h4>A Style Guide for README files</h4>

<h2>Contents</h2>

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

<ul>
<li><p><strong>Project Titles</strong> as a level-1 heading</p>

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

<ul><li>what it does</li>
<li>why you might want to use it, and why you might not</li></ul></li>
<li><p><strong>Example Usage</strong>: a basic example. Nothing fancy -- put rich examples in the detailed usage section</p></li>
<li><p><strong>Getting Started</strong></p>

<ul><li>installation &amp; prerequisites</li>
<li>how to run examples and tests</li>
<li>include a <code>Procfile</code> to start any necessary servers or daemon processes</li>
<li>location of:</li>
<li>code</li>
<li>issue tracker</li>
<li>wiki</li>
<li>blog posts, screencasts, etc</li>
<li>compiled documentation (add the project to <a href="http://rdoc.info">rdoc.info</a>)</li>
<li>travis-ci results</li>
<li>mailing list</li></ul></li>
<li><p><strong>Design Goals</strong></p>

<ul><li>lightweight or full-featured?</li>
<li>performance, flexibility, expressiveness?</li></ul></li>
<li><p><strong>Detailed Usage</strong></p>

<ul><li>models and interface</li>
<li>examples</li>
<li>configuration</li>
<li>middleware or plugins</li>
<li>how it works</li></ul></li>
<li><p><strong>Comparable Tools</strong></p></li>
<li><p><strong>Developer info</strong></p>

<ul><li>Important Components</li>
<li>layout of internal code tree</li>
<li>Limitations and known issues</li>
<li>performance and benchmarking</li></ul></li>
<li><p><strong>Colophon</strong></p>

<ul><li>Credits -- everyone who has contributed code, libraries from which we've borrowed code.</li>
<li>Copyright and License -- state the license type (typically "Apache 2.0" or "All Rights Reserved and Confidential") and refer to the <code>LICENSE.md</code> file. Don't paste the license contents in here.</li>
<li>How to contribute</li>
<li>References</li></ul></li>
</ul>

<h2 id="formatting">Formatting</h2>

<ul>
<li>Call the file <code>README.md</code>.</li>
<li><p>Write in markdown format.</p>

<ul><li><p>You should use triple backtick blocks for code, and supply a language prefix:</p>

<code>ruby
def hello(str)</code>
<code>  puts "hello #{str}!"
end
</code></li></ul></li>
<li><p>Do not wrap lines. In emacs, enable the <code>longlines-mode</code> to make your document word wrap intelligently.</p></li>
</ul>

<h2 id="supportingdocumentation">Supporting Documentation</h2>

<p>Besides a <code>README.md</code>, your repo should contain a <code>CHANGELOG.md</code> summarizing major code changes, a <code>LICENSE.md</code> describing the code's license (typically Apache 2.0 for our open-source projects, All Rights Reserved for internal projects), and a <code>notes/</code> directory that is a git submodule of the project's wiki. See the <a href="https://github.com/roachhd/style_guide/blob/master/style-guide-for-repo-organization.md">style guide for repo organization</a> for more details.</p>
</section>