---
title: How To Write A Great README
teaser:
tags: open source
author: Caleb Hearth
published_on: 2013-05-19
---

Leadership is often defined as having the ability to make others want to do
what it is that you would like them to do. You want people to want to use your
software, and often their first introduction will be through the README in the
source code or on the project's GitHub page.

## The Basics

There are of course components to a technical document that make it more
effective. Describe what it is that your project makes easier. Provide code
examples detailing how the use of the library. Document the installation
process. These are the basic elements which define a README.

Creating a great face for your project, however, requires still more.

## Don’t get lazy just because this is for developers

Technical writing is still writing, and need not be dry and boring. Just as
if you were writing an essay or blog post, you should strive to grab the
attention of your reader early. This can be easily accomplished with a [well-written
introductory paragraph][intro-paragraph]. Use strong or emphasised text to give a short
description of what the software does, such as **"[Receive emails in your Rails app][receive-emails]"**. You can also use an image which relates to the [functionality of your library][library-functionality] or alludes to some pun in the name.

[receive-emails]: https://github.com/thoughtbot/griddler
[intro-paragraph]: http://writingcommons.org/process/organize/paper-structure/396-how-to-write-an-engaging-introduction
[library-functionality]: https://github.com/play/play#background

Your readers will most likely view your README in a browser. Please keep that
in mind when formatting its content. Put the name of the library in an
`<h1>` at the beginning of the file. Categorize content using two or
three levels of header beneath. Make use of emphasis to call out important
words. Link to project pages for related libraries you mention. Link to
Wikipedia, Wiktionary, even Urban Dictionary definitions for words of which a
reader may not be familiar. Make amusing cultural references. Add links to
related projects or services.

## The code matters

Besides speaking English, your readers also understand code. Developers love to
see code samples, and a few lines of *syntax highlighted* source are
worth a thousand words. [`plataformatec/simple_form`](https://github.com/plataformatec/simple_form)
does an excellent job of providing code examples as well as explanations for
nearly every setting and interface call. Besides being extremely [greppable](http://en.wiktionary.org/wiki/greppable), `simple_form`'s
README is the top Google hit for nearly all `simple_form` searches.

Be aware that sometimes the reason someone is visiting your project's page is
that they have a problem. If you know about persistent issues, such as
resolving a functional dependency, call that out in a section of its own and provide a solution or workaround. Right in the README. Yeah. A great example of one such issue is [`thoughtbot/capybara-webkit`][capybara-webkit]’s dependency upon `Qt`. Because a gem cannot satisfy this dependency, we [added a notice][cw-notice] about installation issues to the README.

[capybara-webkit]: https://github.com/thoughtbot/capybara-webkit
[cw-notice]: https://github.com/thoughtbot/capybara-webkit#qt-dependency-and-installation-issues

You are also encouraged to add "badges," such as [Travis CI](http://travis-ci.org)’s ![image][travis-badge] or [Code Climate](http://codeclimate.com)'s ![image][cc-image] to your README, but remember that they reflect on your project—a passing build with high quality code attracts developers to your library, while a failing master build can give them pause.

[travis-badge]: http://media.tumblr.com/6df8b0d6154a26601b9a3ef1c9662de7/tumblr_inline_mn2e2keoSG1qz4rgp.png
[cc-image]: http://media.tumblr.com/7e8748c62e5e2d21e298b865424c2e77/tumblr_inline_mn2e2wmbOH1qz4rgp.png