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?