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. 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 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
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, we 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.
