Updates will be kept to every 2 weeks at a maximum
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?
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.
|Repo name|| || || || |
|Build status badge||✓||✓||✓||✓|
|Library version badge||✗||✗||✗||✓|
|Introduction||129 words||0 words||100 words||19 words|
|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||✓||✗||✗||✗|
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:
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:
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.
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
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.
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.
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.
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:
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.
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.
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.
It’s important to not just document how to handle success, but also failure in your API. Pusher does an excellent job at this.
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.
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.
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!