42

On the Q&A site, voting lets me distinguish between good and bad answers (also, questions).

What purpose does voting have on the Documentation site?

It's probably not the same purpose - the various topics, while sorted by vote count, don't directly compete (or do they?).

On the tour, the only mentions of voting are

anyone can ... downvote

and

Reputation is earned by ... contributing to examples that are upvoted

So, why should I vote? The tour suggests that the only effect of voting is reputation.

If I upvote one topic and downvote the other, does it create any difference for people that read the documentation?


Additional thoughts:

There currently are no tooltips on the voting buttons. This post basically asks "What should we put in these tooltips?".

Also, when I downvote a topic, it asks me for feedback:

I am downvoting this example because it is...

  • not helpful
  • very low quality
  • not clear
  • other

This is great! However, I don't see a compelling reason for upvoting - any documentation is supposed to be helpful and clear; I don't want to specify that it is indeed the case all the time.

A thought experiment - remove the upvote button, and call the downvote button something like "request improvement". How would that be worse than current situation? (disclaimer: this post is not a feature request; this is purely a thought experiment I did for trying to answer my own question).

5
  • 2
    AFAIK it is anticipated to order by popularity: helpful/important topics on the top, niche topics at the bottom.
    – bwoebi
    Jul 24, 2016 at 19:00
  • 3
    I've been upvoting content I consider useful and downvoting content I don't consider useful, just like I would with Q&A, but they probably should add some tooltips.
    – ivarni
    Jul 24, 2016 at 19:14
  • 1
    Some earlier talk about the possible purpose by BoltClock: meta.stackoverflow.com/a/328898 and by Nicol Bolas: meta.stackoverflow.com/questions/329183
    – jscs
    Jul 24, 2016 at 19:16
  • 1
    Downvotes seem to translate into Improvement Requests, but it's not clear what the difference is meant to be. (One practical difference is that a "Flag" IR lets you attach commentary.)
    – jscs
    Jul 24, 2016 at 19:17
  • I'd think higher vote counts help separate particularly useful / insightful examples vs. not so useful ones. Jul 24, 2016 at 20:08

1 Answer 1

13

Voting serves a similar purpose as on Q&A:

  • to reward folks who have provided helpful information (upvotes)
  • to indicate there is a problem with content (downvotes)
  • to bring the most likely to help content to the top of the page (upvotes - downvotes)

There are some difference between Documentation and Q&A, naturally.

In Documentation, downvotes become improvement requests. This is because Documentation aims to be more canonical than Q&A so if there is a problem, someone needs to check the content and improve or delete it (assuming the downvote is valid). Leaving a downvoted example around is much more harmful than a downvoted answer, potentially.

Documentation upvotes reward all contributors, instead of just the owner, again because Documentation is meant to be more canonical. It just makes less sense for a single person to own an entire example (or topic) forever.

Sorting of examples is most similar to Q&A. In Documentaiton we want the most-likely-to-help-a-random-passerby examples to be the first one on the page.

The missing tooltips are a good point, we'll get something (shorter than this whole post) into those in the immediate future.


Don't focus too much on the relative sorting of Topics. In Q&A, the relative sorting of Questions isn't a main purpose of voting. Vanishingly few people browse questions lists on Stack Overflow to find their answer, nearly everyone (> 95%) comes in through a Google search.

We embraced this behavior for Q&A, and are doing so again for Documentation. The order of topics in a list is optimized for people trying to contribute, consumers come in through Google.

6
  • 13
    The fact that people get reputation from upvotes is strange though considering Q&A community wikis don't give reputation. One issue with upvotes is that it's rewarding all of the contributors at once, instead of being proportionate to how much they contributed. To this day, I'm still getting rep from contributing to this topic, even though all of my contributions have since then been reworded and basically replaced.
    – 4castle
    Jul 25, 2016 at 17:36
  • 2
    @4castle Community wiki in Q&A is incredibly rare - multiple contributors are the norm for Documentation. Contributors should be rewarded for useful documentation, the same way people are rewarded for helpful answers. We're actively tweaking the system to get it right, our first pass was tested in the private beta - full Stack Overflow has revealed more issues, which is to be expected (we kept tweaking Q&A rep rules for years). Jul 25, 2016 at 17:41
  • 5
    Similar to what @4castle points out, the Java | Creating and Initializing Arrays example has been edited 69 times, as of now. I threw in an upvote around the 24th edit, because I liked the edit. The example has changed considerably since then, and I don't like it anymore. Do I remove my upvote and wait till it resembles what it previously had? Can I upvote the 24th edit and downvote the 69th edit? Jul 25, 2016 at 17:45
  • 2
    Thanks so much for everything you're doing. You've taken on a big task, and I appreciate how much work you guys are putting into this. I'm looking forward to the next status update from you guys.
    – 4castle
    Jul 25, 2016 at 17:46
  • 4
    When Stack Overflow was brand-new (still in beta) and editing was still getting figured out, there were numerous proposals to make editing earn reputation for editors @4castle, and some sympathy from the staff (well, Jeff) for figuring something out there. However, it quickly became apparent that this would be fiendishly complicated and ripe for abuse... So the idea was shelved. Chances are, it's still fiendishly complicated and ripe for abuse, but Docs provides a good test-bed for figuring it out finally.
    – Shog9
    Jul 25, 2016 at 17:46
  • 2
    In "bring the most likely to help content to the top of the page", what does "page" mean - the Google-search-results?
    – anatolyg
    Jul 25, 2016 at 19:20

Not the answer you're looking for? Browse other questions tagged .