Proposed supplement to (or overhaul of) the "Make Your Own Gem" tutorial

[rlue]

I originally mis-filed this issue under the rubygems/rubygems.org repo (#1597), and am migrating it here for further discussion.

In short, I think there are two important improvements that could be made to the official guide, and would like to know if the maintainers would be open to incorporating a modified version of the alternative guide I wrote on my blog.

1. Discuss what's going on under the hood of the RubyGems system.

Newcomers to programming would benefit from a guided introduction to the habit of tinkering with a system to see why things work the way they do and how a change in one place produces a change in another. For example, the guide briefly covers the creation and purpose of a gemspec, but it totally misses the opportunity to examine the gemspec from an established project and use that as a way to discuss convention (like specifying a gem's version number in a lib/<gem_name>/version.rb file). The line below is as close as it comes:

The gemspec defines what’s in the gem, who made it, and the version of the gem. It’s also your interface to RubyGems.org. All of the information you see on a gem page (like jekyll’s) comes from the gemspec.

Note that there is no mention of where to find jekyll's gemspec, and no excerpt of its source.

Without a discussion of what a .gem file is made of and what you can do with it, it's nearly impossible to deviate from the steps prescribed in the guide. In the end, RubyGems still feels like incomprehensible magic, which does not empower readers to go out and build something of their own.

2. Address the distinction between building a library and publishing a gem.

Building and publishing a library can mark a budding programmer's first steps into a software community of any kind. When I was setting out to build my first gem, I did not yet understand how things were supposed to fit together or what the conventions and best practices were. The official guide does touch on all the important bits — splitting code into multiple files, creating binaries, testing your code, writing documentation, etc. — but each one is given a very short treatment, where most really deserve a book's worth of elaboration. When I read it, I came away with the impression that tests, documentation, and code organization were tasks to be completed, rather than subjects to understand or skills to develop.

Given that the guide is written as a step-by-step tutorial, this quick flyover conflates the vast complexity of software development with minutiae of software packaging. The bits about building a library deserve to be extracted into a separate guide, with each section containing links to resources for where to learn more.