How to Write a README

There is a science and an art to writing an effective README for an open source project.

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 on the GitHub project.

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. Use strong or emphasised text to give a short description of what the software does, such as Receive emails in your Rails app. You can also use an image which relates to the functionality of your library or alludes to some pun in the name.

Your readers will most likey 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 does an excellent job of providing code examples as well as explanations for nearly every setting and interface call. Besides being extremely 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’s dependency upon Qt. Because a gem cannot satisfy this dependency, thoughtbot have added a notice about installation issues to the README.

You are also encouraged to add “badges,” such as Travis CI’s build status or Code Climate’s GPA 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.