This is part of an ongoing series. Read the first entry for context.

Most people coming to Stack Overflow who don't know much about a tag are passive consumers. A small percentage (of a huge number) will ask a question. People tend to assume only experts should answer, but I think answering is a good way to learn. My hope for Documentation was that it'd be an even easier way to learn via Stack Overflow. (I was wrong.) To test that theory, I figured I might as well use ignorance of Ruby to my advantage.

Documentation had a great feature where people could ask for someone else to write a topic. Knowing almost nothing about Ruby, I didn't know what was lacking in the Documentation, so I was excited to see art-solopov's request:

Option Parser

The examples on how to parse command-line options in Ruby using its OptionParser class, including the examples on how to set default values and mandatory options.

Indeed, this was a useful request since the official documentation includes these amusing notes:

The following example is a complete Ruby program. You can run it and see the effect of specifying various options. This is probably the best way to learn the features of optparse.

. . .

Further documentation

The above examples should be enough to learn how to use this class. If you have any questions, file a ticket at bugs.ruby-lang.org.

So, yeah. The official documentation isn't great and knows it. It's not helped that command line syntax is kinda standardized haphazardly. Over the years a bunch of conventions have accumulated that a sophisticated program really needs to observe. Each language offers a unique method to parse the command line, but it's tedious to document everything in detail.

Perl's Getopt::Long module has excellent documentation that goes into detail. It's how I learned to parse the command line and it made coming to Ruby's sparse documentation less painful. I can't imagine someone who has to learn everything from scratch getting anywhere with it. So I wrote an OptionParser topic, submitted it for review and made Kathryn's first contribution to Stack Overflow.

My first review!

You can read the topic on archive.org. To be honest, it's not spectacular. At some point, Ruby added a built-in why to specify required arguments, which invalidates one of my examples. I'm not really convinced it would actually help anyone who didn't have a working knowledge of command line syntax. But it was a start and writing it helped me to understand how the Ruby module works. I also got 2 points of reputation and my first substantial badge:

My achievements!

At Stack Exchange, we spend a lot of time thinking about badges and reputation notifications. For the first contribution to the site, you are certain to get at least a bronze badge. We also notify folks of upvotes (but not necessarily downvotes), which encourages people to do more of whatever it was they did to get an upvote. This is all basic behavioral psychology and it works brilliantly.

After getting this little burst of reinforcement, I wanted more. So I decided to search for optparse questions to answer with my new-found knowledge:

And so began a pattern of writing a bit of documentation and then poking around to find questions I could answer with new-found knowledge. Documentation rewarded this behavior by offering an extra 5 reputation points for the first upvote of an answer linking to a topic or example I contributed to. As I answered questions, I also noticed problems in the documentation (both the official stuff and the topics I'd authored). So I'd use that discovery to edit my topics. It was a very productive feedback loop; at the end of one day I had earned 37 reputation.

The bulk of my 1k reputation came from answering questions based on Ruby features I just learned about. Very little came from writing documentation directly. But by picking very narrow features of Ruby, I can productively find questions I'm uniquely suited to answer.

Next time: I get around to asking a question.