Developer Experience: GitHub READMEs

The README.md for a project on GitHub is often the first thing developers see when they encounter your product. The README for a library can be the starting point in a developers relation with your product. These text files serve both as a technical guide to your library and as marketing material for your product. So what should be in a README and what is better avoided?

An analysis

For this article I’ve done a little survey across the SendGrid, Pusher, Stripe and Twilio Ruby libraries. I’ve also taken a screenshot of each README and put them in a handy little gallery for future reference.

  SendGrid Pusher Stripe Twilio
Repo name sendgrid-ruby pusher-http-ruby stripe-ruby twilio-ruby
Build status badge
Library version badge
Introduction 129 words 0 words 100 words 19 words
Install instructions
Installation requirements
Get Started samples
Link to docs
Link to Ruby specific docs
Link to API credentials
Link to support
A LICENSE file
A CHANGELOG file
A CONTRIBUTING file

Clarification: I’d like to make it clear that I am not saying any of these README’s are good or bad. I think all of them have good things and bad things, which have probably come about for very good reasons.

README template

While a README is a good starting point for a developer it is a limited tool. It’s just a flat file with very little option for structure or design elements - add too much to a README and it becomes wieldy and hard to process.

A reasonable template for a README, as much as there can be one, would be:

  1. Inform the developer * about your product * about the SDK/library * what the license is * how to contribute
  2. Get started with * installing the library * getting the API keys * making the first API call
  3. Document common API calls * including method arguments * including how to handle responses
  4. Link out * to the full developer documentation * to the developer dashboard * to support channels

Do you prefer to learn by example? Have a look at this Example README I’ve put together for you. Make sure to read the WHAT_IS_THIS.md for more information.

1. Inform

The first task of your README is to inform your user what your product does, and how your library or SDK helps to make this happen. I think Twilio does an excellent task at this:

Twilio

Repo name

Ideally your repo name should be [company_name]-[language_name], for example twilio-ruby. Of the 4 providers I surveyed only Pusher deviated from this.

Repo title

The repo title should be short and simple. Ideally it has your company name, and the word library or SDK. You could call it a wrapper for your API, but that’s what a library or SDK really is, so why use a different word. Additionally you could add some explanation as to what your product does. For example, Twilio’s repo could be called:

Twilio SDK - Send and receive text messages and calls with Ruby

Badges

Twilio uses a few badges badges. The 2 I think are important are firstly the one for their library version, and secondly one to show the current build status for the code in the master branch.

To get your own version badge I recommend having a look at Version Badge.

Introduction

The introduction of your library should be short and to the point. it should explain what your product does and how this library helps with that.

Twilio’s intro is short and simple. It’s 19 words, explains what the library does, and then links to the official docs. I’d say the one thing missing here is that it does not explain what Twilio is for those uninformed.

LICENSE, CHANGELOG, CONTRIBUTING files

There are a few standard files that are always good to have in your projects.

If you want you could link to these from your README file.

2. Get Started

After you’ve informed a developer about your product and its library, the next step is to get them started with initializing and using your product. In this let’s look at a different company, InterFAX:

InterFAX

Install instructions

The first step is to explain how to install your library. If possible explain how to install it the most common way, and maybe the second most common way. Some languages only have one real way to install a library but not all do. Look at existing libraries for the same language for examples.

Install requirements

It’s important to add some guidance on the language, platform, and any other requirements your library may have. I recommend linking to the install instructions for those dependencies where possible.

Finally, and this is often forgotten, it’s important to provide a link, or some instructions, on where a developer can find their API credentials. If this is not provided it might prove very hard for a developer to get beyond this step.

3. Document

After the developer has successfully installed and initialized your library it’s time to have them actually use your product. Think about what’s the first step someone would want to take and get them started.

It can be easy to add too much information in this section so here are some guidelines.

Do’s

Don’ts

It’s important to not just document how to handle success, but also failure in your API. Pusher does an excellent job at this.

Pusher

After the developer has made their first API call they’re ready to move on. This is ideally where developers leave the README and continue to your developer documentation on your site. If you have more Get Started guides and Tutorials on your site then this is where to point them next.

Ideally you should link to a few places in your documentation. The developer has just made their first API call but this is most likely not their last. What is the logical next step in this process? Link them there!

If possible I’d link to the documentation in their programming language, so they don’t have to select this again. Additionally linking to the full reference docs as well as guides is very useful for those already familiar with your platform looking to make changes.

Finally, make sure to link to your support channels, whether that is email, Twitter, or other. SendGrid does an excellent job at this.

SendGrid

Allowing developers to find you and get a quick response to technical questions can prove to be a major factor in converting a developer into a success story.

Hire me?

I am a freelance Developer Experience designer. If you want to know more about my work have a look at my portfolio and if you’d like for me to help improve your company’s Developer Experience then most definitely reach out to me via Twitter or email!


Subscribe to new articles

Updates will be kept to every 2 weeks at a maximum



Related Articles

Developer Onboarding: GitHub
Wednesday April 12, 2017
Understanding Developers
Thursday February 23, 2017
comments powered by Disqus