What should be in a gem's README?

Ruby Chat
#1

When considering using a gem, I depend upon its README to get a sense of whether it will solve my problem. Is the gem adequately documented? What problems does it solve? How is it different than other, similar gems?

Things I like to find in a README

  • A self-contained description of this gem. Don’t just tell me that it’s a better version of some other gem. Tell me what it does without me having to know what that other gem does.

  • Why this gem instead of that other one? – What itch does it scratch? Is it better documented? Does it solve a slightly different problem?

  • The simplest possible self-contained “hello, world” example showing how to use the library. This answers the questions, “What do I require?” and “What object do I make first?” Figuring out which object to make first and how to make it isn’t always obvious. If you show me that, I can often figure out the rest.

  • Beyond the “hello, world” example, what are the most common options and uses?

  • Links to rdocs, the rubygems.org entry, applicable standards, wiki pages, other documentation.

  • What Rubies does it work on?

  • What OSs does it work on?

That’s my list. What’s yours?

1 Like
#2

One thing that I have often wished for was screenshots or a link to a sample app showing the gem in action (when possible). Basically I shouldn’t need to install the gem to see what it actually does.

2 Likes
#3

BADGES!

At least the CI badge. That shows how much the author(s) caring about the gem (I assume)
A communication channel would be good to have (IRC, Gitter, etc.). I don’t think GitHub (or whatever hosting service you are/will be using) is good enough for small topic / ad-hoc discussion.
Gem version badge is a good to have (since what’s on master might not be what’s released)

Actually I want CHANGELOG most of the time, but I guess this is talking about README only…

2 Likes