Crafting a README

When looking at a project for the first time, a README file is often the first place many users will go to get information on how to work with a program or library. For developers it’s often a challenge to figure out what to put in the README file, as there is uncertainty as to what the users expect when reading the file. This article introduces a template that I often use for writing README files, based on both writing packages and utilizing them. Examples are given in a generic text format, but it is recommended to look into MarkDown if the project is intended for sites such as GitHub.

What Does It Do?

The first part should state plain and simple what the project does. If it’s meant to replace another project, it should state what the shortcomings are of the other software that caused a different package to be necessary. It should also list any features that make the package stand out.

= Introduction =

This is a Ruby library to interface with the FooBar API. It was created due to the fact that there are only Python bindings available to interface with it. Some notable features:

* oAuth authentication support
* SSL communication
* Results caching to lower API hits
* Supports version 1.0 and 2.0 of the API

What Is Needed To Use It?

Perhaps one of the most important items from a software packaging perspective is what is needed to use the package. Unless the package is targeting a specific OS, dependencies should point to the project homepage and not the distribution specific package. However, distribution specific packages can be added as an addition to the base content so users don’t have to search around for the package on their specific distribution.

If the package is something that requires compilation (a ruby library against C bindings for example), the build requirements should be provided as well. For packages that run under interpreted languages, the language runtime version should also be indicated (Ruby 1.8/1.9, Python 2.7/3,2, Java6/7, etc.)

Finally, any mention of modules, libraries, etc. should be listed out if they are bound to configuration options and not bundled with the language runtime.

(= Requirements =

This code has been run and tested on Ruby 1.8 and Ruby 1.9.

)

== External Deps  ==

* curb (https://github.com/taf2/curb) for curl based calls (allows for setting of custom headers)
* nokogiri (http://nokogiri.org/) for parsing the XML response
* sqlite-ruby (http://sqlite-ruby.rubyforge.org/) for cache storage

== Standard Libary Deps ==

* OpenSSL for cryptography functionality

How Do I Install It?

This may be a simple command such as gem install foobar for installation. However, the user may wish to do a source installation, so it’s important to show instructions for that as well. Recommended installation instructions for various distributions can be added in addition if a package version of the project is available.

= Installation =

This package is available in RubyGems and can be installed with:

   gem install foobar

For users working with the source from GitHub, you can run:

   rake install

Which will build and install the gem (you may need sudo/root permissions). You can also chose to build the gem manually if you want:

   rake build

Ubuntu users can install this package by executing:

   sudo apt-get install ruby-foobar

Note: If you use bundler to create a gem through bundle gem it will generate much of this README content for you

How Do I Test It?

It’s beneficial to both the user and the developer to have a method of testing. This allows users to ensure basic functionality for reporting bugs. It also gives the developer a place to point users to for filtering out any local environment issues preventing the package from working. This should list the commands necessary to test the package.

= Tests =

An RSpec test suite is available to ensure proper API functionality. Do note that it uses the staging version of the API, and not the production version (to prevent hitting API limits should something go wrong). Tests are set as the default rake target, so you can run them by simply executing `rake`

Where Can I Find More Information?

Here is where the project website should be listed. This could be a dedicated site with its own domain name, a listing on RubyDoc.info, or something as simple as a GitHub repository link. It should also include ways to build API documentation if there is any.

= More Information =

More information can be found on the [project website on GitHub](http://github.com/myuser/myproject). There is extensive usage documentation available [on the wiki](https://github.com/myuser/myproject/wiki).

== API Documentation ==

The main API is documented with yardoc, and can be built with a rake task:

   rake yard

from here you can use the yard server to browse the individual gem docs from the source root:

   yard server

or optionally you can run the main yard gem documentation server:

   yard server --gems

and docs can be viewed from `http://localhost:8808/`

How do I use it?

This is by far one of the most important sections. Users often want to see a small piece of code to get them started on basic usage. This can be a simple connection and data loop, or it can be more extensive and show multiple examples for popular usage. Any examples in the source directory should be noted as well.

= Example Usage =

The following shows how to connect to the API and print a list of users:

   -*- encoding: utf-8 -*-
   require 'foobar'

   api = Foobar::Api.new('[key]','[secret]')
   api.GetUsers().each do |user|
       puts "User: #{user.name}"
   end

What Are The License Terms?

This section should list the location of the LICENSE file, as well as what type of license it is. It’s especially important to note cases where there are multiple licenses, or an alternative commercial license available.

(= License =

This project is licensed under the MIT license, a copy of which can be found in the LICENSE file.

)

How Do I Get Support?

For those who want support, the necessary procedures should be explained. This could be anything from a mailing list to pull requests.

= Support =

Users looking for support should file an issue on the GitHub issue tracking page (https://github.com/myuser/mypackage/issues), or file a pull request (https://github.com/myuser/mypackage/pulls) if you have a fix available. Those who wish to contribute directly to the project can contact me at <[email protected]> to talk about getting repository access granted. Support is also available on IRC (#foobar @ Freenode).

Conclusion

This concludes a look at crafting a README file for users to better understand a project. Note that these are what I would consider guidelines, so projects may choose to add more content, or take out sections based on individual project needs. However, it’s also important to note that a detailed and well thought out README can go a long way towards encouraging users to try a package out and can even help entice contributers.