Я всегда люблю хороший README. Гораздо проще прочитать хорошо объясненный README, чем просматривать автоматически сгенерированное руководство по RDoc. README должен объяснить, что делает гем и как его использовать, с примером кода и даже некоторыми продвинутыми примерами, которые могут быть включены в конец README.
Другим важным файлом является файл истории или CHANGES. Этот файл должен содержать объяснение основных изменений между выпусками. В него не нужно включать подробности, но должно быть достаточно информации, чтобы кто-то, переходящий с версии x на версию y, мог быстро увидеть, что нового (чтобы вы могли оценить преимущества обновления) и что изменилось (чтобы вы могли оценить потенциальное влияние обновления на ваш текущий код).
Слишком много раз я вижу проекты, в которых отсутствует файл CHANGES, и вы практически не знаете, что изменилось при запуске обновления.