I started this series expecting to write extensively on Stack Overflow Documentation. But sadly I had to start writing about shutting it down instead. My third post was originally going to be about a small, but irritating edge case. Since the flaw will soon be history, I decided to move on to more positive things about Documentation. In particular, how it didn't really destroy Stack Overflow's reputation system the way many assumed it would.

Now, to be fair, reputation was broken on launch day. So you might be forgiven if you assumed it was easy to make bank with minor edits. But my experience showed it was, if anything, too difficult to earn reputation writing Documentation. As you'll remember, my goal was to earn 1k via Documentation contributions. And I certainly didn't slack on the effort:

I wrote all or most of 11 examples and edited 2 more. Most¹ of these edits earned me +2 reputation just for getting through peer review. However, in two months of activity, only 1 of my examples was upvoted. It didn't take long for me to realize I'd never get to 1k that way. Fortunately, there are other ways to earn reputation from Docs, such as linking to something you contributed to in an answer that got upvoted. But none of those reputation sources were particularly rich either:

Reputation change	Reason
60	Doc Link Upvoted
20	Proposed Change Approved
5	Example Upvoted
-5	Doc Rep Source Removed

In my opinion, much of the angst about reputation surfaced because of a fundamental misunderstanding of the goal of the system. I get the feeling that a lot of people think of reputation as either a form of currency or a measure of talent or knowledge or skill. But listen to how Jeff Atwood answered a listener question on Podcast #13:

Isaac Moses: How do you plan to get people who know stuff to keep coming back to your site, and find questions that they know the answers to? Thanks, 'bye.

. . .

Atwood: I don't really like to buy a lot of consoles, it's just — there's a lot of hidden costs, and I'm really a PC gamer, I'm sort of a, again, I'm a snob, I'm a hardware snob, so of course I'm not gonna be into that, but Rock Band really pushed me over the edge. And one of the things I found after reading about achievements, I was like, "Oh, that's dumb." You know, as you play the game, you do things, and you get these little badges, these achievements that show up in your profile online, so people can see them. See, that's the key thing — other people can see them, that's the really important piece of this. I was like, "Oh, that doesn't matter." And then, as I played the Xbox 360, I got these achievements, and I became totally obsessed with them. I was like, "I have to have all these achievements for these games that I like," right? Because I just, I want them, I must have them! [laughs]

It's amazing how quickly I turned around on that, so when it came to Stack Overflow, I was like, I want to have something like achievements in Stack Overflow. So we have this "badges" system, which is very much analogous to Xbox 360 "achievements".

Stack Overflow's reputation and badge systems are modeled after (and themselves are) extremely successful token economies². Now the quote isn't about reputation, but the same principle applies: these systems are designed to get users to come back for more. The mechanism is simple:

1. Users post a question or an answer.
2. Other users vote on the usefulness of the post.
3. The user's reputation goes up or down based on voting.
4. Over time, reaching new reputation levels grants new privileges on the site.

There are a number of other nuances built into the system to encourage and discourage other behavior, but most reputation is based on voting on posts. So the answer to Isaac Moses question is that people who know stuff will write useful answers which will get upvoted which increases their reputation and gives them more say in how the site operates. It's a virtuous cycle that gets people to do more of what they already feel rewarded for doing.

That upvotes come from other users approving of your work magnifies the cycle. While there's some randomness surrounding who might see your work and when, an upvote always means someone else has vetted your skill as a programmer and writer. Even when upvotes don't provide reputation (such as comment upvotes), it feels fantastic to get one. Documentation had, if anything, a more powerful system of peer approval in that every edit required other people to review it. Getting a change approved meant someone else had really read³ what you wrote.

But Documentation utterly failed to be addictive because almost nobody voted on examples. Maybe it was because the examples weren't useful or because nobody saw them in the first place. Whatever the reason, no votes means no tokens and no positive reinforcement. Ultimately, I didn't need any Documentation reputation to reach 1k. It was a non-factor.

Next time: I begin learning Ruby by writing (and reading) documentation.

---

Footnotes:

1. If you edit several examples at once or if you were the last person to edit a topic, you only get one +2 bonus. ↩

2. Despite the sound of the name, token economies are not currencies. Unlike dollars (or, I guess, Bitcoin) you can't spend reputation on just anything. It's only valuable to people who have bought into the system in some way or another. In fact, if reputation ever did become fungible it would stop working immediately. ↩

3. And just to be sure, we audited reviewers by occasionally inserting faked junk edits. Reviewers who failed audits weren't allowed to review anymore. ↩