83

Currently, a proposed change to a documentation topic can be rejected by one person. I feel that gives too much power to anyone who doesn't like a proposed change for no good reason. For example, code style, bad English, or (hopefully rarely) just "I hate you."

I think at least two people should be required to reject a proposed change. That way, someone needs to agree with the reason the first rejector gives. Your thoughts?

9
  • 41
    Same thing with accepting changes. Too many people adding little or no value or adding irrelevant detail that detracts from the intention. Should require more than one person to accept or reject imo.
    – Galik
    Commented Jul 21, 2016 at 22:46
  • Maybe reviews should be ongoing and new reviewers can vote to approve even if it got formally rejected earlier, but was actually valid, so there would be no need to create another edit proposition (on which the rejecting reviewers could vote to reject again)? Commented Jul 21, 2016 at 22:47
  • @Galik Currently, 2 people are required to accept. That changed from 1 when the public beta started.
    – tbodt
    Commented Jul 21, 2016 at 22:47
  • @tbodt That's good, id be tempted to make it 3 tbh but 2 is better than one
    – Galik
    Commented Jul 21, 2016 at 22:49
  • 2
    "Currently, 2 people are required to accept" Unless this changed in the last ten minutes, this may vary by rep of the suggester. The little green popup after I submit a proposal indicates that only one approval is needed. Or that description could be a bug.
    – jscs
    Commented Jul 21, 2016 at 22:50
  • @JoshCaswell That description is probably a bug, I've approved quite a few changes since the beta started and they don't disappear from the list until/unless some else approves them.
    – tbodt
    Commented Jul 21, 2016 at 22:52
  • 1
    @tbodt Nah, it just depends on the type of change. (See my answer.)
    – Adam Lear StaffMod
    Commented Jul 21, 2016 at 22:52
  • 1
    I'm not sure...I also appear to be able to single-handedly approve.
    – jscs
    Commented Jul 21, 2016 at 22:53
  • This seems like a tough thing to do in the beginning. It means you need at least twice as many reviewers as content-creators. I could easily see the number of review tasks overwhelming the reviewers. Commented Jul 22, 2016 at 16:24

8 Answers 8

17

I agree with your position, but I disagree with making it a static number of approvers.

The number of approvers required should be a dynamic number based on the size/popularity of the topic. For instance, Java should require more approvers than something more niche like Jsoup (~3 contributers). Otherwise less popular topics will sit for days (or maybe weeks) without the required number of approvers.

1
  • 1
    I really like this idea.
    – tbodt
    Commented Jul 25, 2016 at 1:58
39

We're trying to strike a balance here between achieving some amount of fairness/review and clearing proposed changes quickly enough that we don't have a backlog in the hundreds.

Unfortunately, there's not much room between "one" and "two". Anyone got half a person handy so we could split the difference? ;)

Seriously, though, I agree that having one person potentially unilaterally rejecting changes over and over is, at best, annoying. I bumped the rejection settings back up to 2. Approvals remain at 1 for now for regular changes and at 2 for topic deletions or version changes.

23
  • 54
    Approvals need to be harder than rejections IMO.
    – Galik
    Commented Jul 21, 2016 at 22:54
  • 7
    @Galik Both need sensible thresholds. As usage evens out (we're at Day 1 here, things are a bit mad), we'll be able to pick something better. For now, we just tweak as issues come up.
    – Adam Lear StaffMod
    Commented Jul 21, 2016 at 22:54
  • 2
    @Galik I fundamentally agree. If single approvals are enough, we also risk bad/low-quality content. Currently docs are all fresh and it's all reviewed over and over, but in future it won't and bad edits may go unnoticed for a longer time.
    – bwoebi
    Commented Jul 21, 2016 at 22:56
  • Should be something like 4 for approve and 3 for reject, or ideally a review queue for docs.
    – Wyetro
    Commented Jul 21, 2016 at 22:57
  • 2
    @WMios We can pick random numbers all day. :) Data and experimenting over time will tell us sensible thresholds. (I can see these even potentially varying by tag.)
    – Adam Lear StaffMod
    Commented Jul 21, 2016 at 22:58
  • @Galik not at this stage though. From SO perspective, it's a good thing.
    – Knu
    Commented Jul 21, 2016 at 22:58
  • @AdamLear, I adjusted my comment. I think a review queue would be helpful to help weed out bad edits.
    – Wyetro
    Commented Jul 21, 2016 at 22:59
  • @knu Some people are putting time and thought into high quality examples that are being trampled on by random people adding irrelevant details that detract from the well-though-out focus. Lots of realy poor quality submissions are getting accepted
    – Galik
    Commented Jul 21, 2016 at 23:01
  • 1
    @WMios Docs sort of have a review queue built in as is. We can do better at making it easier to review changes across multiple tags and such - this is yet another thing that we'll figure out better as the beta goes on.
    – Adam Lear StaffMod
    Commented Jul 21, 2016 at 23:01
  • 3
    @AdamLear I feel like for small tags (let's say < 50 topics), one approval/one rejection is fine… then we can gradually increase to 2 approvals /2 rejections for < 300 topics and above that 3 approvals/2 rejections or similar. From what I've seen today, the smaller a tag it is, the more it's reviewed anyway and doesn't need much approvals/rejections. Only when they grow bigger it's less reviewed....
    – bwoebi
    Commented Jul 21, 2016 at 23:02
  • @Galik I completely agree. Eternal September SO flavoured.
    – Knu
    Commented Jul 21, 2016 at 23:07
  • 1
    @AdamLear Any plans/thoughts on letting people with gold/silver badges in that tag have a documentation equivalent of Mjolnir? Perhaps even having their changes require fewer approvals too?
    – DavidG
    Commented Jul 21, 2016 at 23:28
  • @DavidG Once we have data to base that sort of decision on, it's not out of the question.
    – Adam Lear StaffMod
    Commented Jul 21, 2016 at 23:42
  • 4
    Rollback wars coming. There will be bloodshed.
    – Comintern
    Commented Jul 22, 2016 at 14:20
  • 3
    This would be OK if rep was not involved. But there are too many people triying to get the free rep that docs give and making small edits, that would be OK in the main page, but not if they give you free rep! Commented Jul 22, 2016 at 14:39
14

Yes, it should take at least three people to both Approve and Reject topic improvements. Or one moderator, for either.

Approvals and Rejections should be considered with the same weight as they're both equally crucial to the getting quality content.

Additionally, we could consider the thought of reducing the requirement to two people for the escalated rejection reasons (spam, rude / abusive), as we want to get it out of the system and dealt with ASAP.

4
  • 19
    Three rejections… Not sure. Approvals are much more important to guard against. Once bad content is there, it may go unnoticed for a longer while. Rejections however are not that critical… you can just resubmit something in case the rejections were bogus.
    – bwoebi
    Commented Jul 21, 2016 at 22:58
  • imo there should be "recent completed suggested edit" review queue for people to be able to keep track of what others accept/reject, like the review queue history on the main site Commented Jul 21, 2016 at 23:08
  • turns out it exists: stackoverflow.com/documentation/… Commented Jul 21, 2016 at 23:13
  • 1
    Maybe a weight for no-badge/bronze/silver/gold in the tag could lighten the requirement of 3 votes, A gold badge owner could probably be trusted as 3 votes, silver as 2, bronze and no badge as 1 ? (unsure where to place bronze owners, kind of highly dependent on the tag)
    – Tensibai
    Commented Jul 22, 2016 at 14:36
6

if one user makes a change, and another approves it, then there is already two people that agree with the change.

whereas if the change is rejected, then there is one person that agrees with the change while another disagrees.

clearly then, in order to have a majority, two people should be needed to reject a change.

(to be clear, this doesn't imply that one vote is enough for accepting a change. that number should be guided by other criteria that are not being discussed in this question)

2
  • I still think accepting should be harder than rejecting but you make a good point.
    – Galik
    Commented Jul 24, 2016 at 10:06
  • i actually agree. after reviewing a change myself, i found it way to easy to just accept it without properly checking it. but both questions don't depend on each other. to have a majority to reject, two are needed, but that doesn't mean that one reviewer is enough to accept a change, it could be two or three as well. the argument here would be that, once accepted, a change is pretty much permanent. at least now, while i expect most people focus on writing new documentation as opposed to perfecting existing material. but that's a topic for another question.
    – eMBee
    Commented Jul 25, 2016 at 1:10
5

I'd like to note that it's just equally easy to just resubmit the original suggestion.

In case this happens repeatedly from a same user, you can always flag and ask the mods to clarify that he can either write what's wrong with it or be banned from documentation reviewing.

I'm not saying this is necessarily a bad idea, but it's not as bad as you describe it.

The clear disadvantage I see here, especially when building new documentation, is that it takes longer to have legitimate edits go through. [At least I assume you will also require at least two approvals in that case for everything. Else it's somewhat missing the point.]

With the current Q&A review queue, we have many diligent people… but documentation changes often require a lot of domain-specific knowledge and thus much fewer people will be able to review it.

8
  • 1
    if you resubmit the same suggested edit, the same rejecting users could reject it again and you're stuck in a loop Commented Jul 21, 2016 at 22:53
  • I've written: In case this happens repeatedly from a same user, you can always flag and ask the mods to clarify that he can either write what's wrong with it or be banned from documentation reviewing.
    – bwoebi
    Commented Jul 21, 2016 at 22:53
  • 1
    Except that there's a review cap but not a suggestion cap.
    – jscs
    Commented Jul 21, 2016 at 22:54
  • But often times its simply differences of opinion between different correct ways.
    – Galik
    Commented Jul 21, 2016 at 22:57
  • @Galik those should be two different examples then, explaining why use either option or that both ways are acceptable. "Improve edit" should be done instead of rejection. Commented Jul 21, 2016 at 23:00
  • @user1306322 That's a nice solution if you can get both to agree to it. But if someone wants to put his info in your original post regardless (because he thinks it should be there) its a problem
    – Galik
    Commented Jul 21, 2016 at 23:04
  • @Galik In this case you always can ask for mod intervention. Or invite him into a chat and discuss first.
    – bwoebi
    Commented Jul 21, 2016 at 23:07
  • @bwoebi: I asked to improve process of communication between contributors and reviewers in meta.stackoverflow.com/questions/329103/… Commented Jul 31, 2016 at 10:07
4

Unfortunately, there's not much room between "one" and "two".

Well, there is. Approvals can be based on cumulative reputation.

1

I wholeheartedly agree.

I've submitted a section of documentation that was rejected out-right. I was not annoyed by that per say, but the reason claimed 'too specific for most users'. I disagree entirely (perhaps this individual hasn't come across this issue) and I am worried that the the level of documentation is going to be relegated to 'this is how you do this' examples rather than providing a bigger-picture view.

This isn't the community effort that 'Documentation' was sold to be.

For context, my submission was in SQL and explaining the difference/warning between null, dbnull and empty strings. I would put this on the same practical level as database normalisation and understanding the difference between primary/foreign keys & technical/non-technical foreign keys. These are all 'sql' related.

Dismissing based on technical accuracy is one thing (and should be encouraged) but what are my options here?

I am concerned that one person with a big stick can decided they want to avoid imparting a 'bigger picture' understanding. It's this kind of insight that will improve the industry.

Am I to create a competing tag that has less chance of being found?

('practical database theory applications' maybe? sounds fun...)

9
  • 1
    note that 2 rejects are now required
    – tbodt
    Commented Jul 21, 2016 at 23:51
  • Thanks for the update, I've re-submitted, see how this goes. My over-all thought is that documentation should be more than an 'if x do y' list... Particularly as that's the whole basis of the stackexchange service proper. Doco can provide the context.
    – Beeblebrox
    Commented Jul 22, 2016 at 0:36
  • I rejected the proposed change because SQL itself has no "DBNULL". ("Too specific" was the most, if not completely, fitting reason.) If .NET languages have a different null and map SQL's NULL to DBNull, then this should be explained in the .NET documentation.
    – CL.
    Commented Jul 22, 2016 at 12:21
  • @CL I think a little bit of explanation in usage for a particular language should not hurt. Commented Jul 22, 2016 at 12:35
  • @AbdulRehmanSayed But not intermingled with the explanation of the differences between NULL and empty strings (which, by itself, would be very useful, and has been requested).
    – CL.
    Commented Jul 22, 2016 at 12:41
  • @CL yet on the submission itself your only comment was 'this isn't formatted correctly'... No matter anyway. I've been completely turned off of contributing now.
    – Beeblebrox
    Commented Jul 22, 2016 at 13:00
  • @Beeblebrox I wrote a comment on the rejection, too; I don't know where that would be shown.
    – CL.
    Commented Jul 22, 2016 at 13:01
  • 1
    @CL you pointed out the content contained within had some use. Why not edit instead of dismiss as a whole? It's a community effort. Yes it takes more than a couple of mouse clicks but that course of action will only rob the site of content/contributors in the future. Regardless, the flaw here is that one person's idea of documentation can negatively affect quality/usefulness. I believe in context being useful by providing a bigger picture view. Save the cut-and-dry 'if x then y' for stackexchange proper.
    – Beeblebrox
    Commented Jul 22, 2016 at 13:18
  • It sounds like what this really calls for is a means of editing the edit and then accepting the edited edit (at which point someone else would have to approve the edited edit or whatever.... Either that or move to a Wikipedia style where edits go in unless someone reverts them, in which case subsequent tweaks become much, much easier. The delays caused by approval are likely to cause serious edit conflict problems if a document is getting a lot of eyes....
    – dgatwood
    Commented Jul 25, 2016 at 2:46
1

If someone has the reputation to edit material, it makes no sense not to allow them to reject a proposed change to it. That user can just wait until the change is voted on, and then have their way with the content.

1
  • Does this exist for Documentation (privilege to just edit parts of it without requiring approval)? Commented Jul 25, 2016 at 14:54

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