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 
or Code Climate’s 
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.