4

I've been using the Review Documentation queue, and I have noticed an irksome pattern.

Regularly I come across proposed documentation changes where: (1) I am able to choose between "Accept" and "Reject" (which is normal), and (2) I also see that a prior reviewer has chosen "Reject" and I can see their rejection commentary (also a good feature, but here comes the troubling part...)

These rejections are frequently based on the same gross misunderstanding.

I can see from the comment that the rejecting reviewer is commenting on the whole text being shown, not the (typically minuscule) portion highlighted in red & green.

[Someone please sanity-check my assumptions: It is just the colored portion that has changed, right? Is it I who has misunderstood how the Documentation review page works?]

My feature request:

  • The UI/UX of the Review Documentation page needs updating for clarity.

I'm not a UX designer, but some ideas:

  • Show less context by default. Home in on showing just the changed phrase/paragraph, with an option to expand the context if needed.

  • Bring the editor's notes front and center and make them impossible to miss. This way it's obvious if the editor described the change as "added one bullet point". Hopefully the reviewer will be better cued to look only at the bullet, and not click "Reject" due to not liking other stuff on the page.

I think this will minimize the pain, wasted time, and confusion of pointless rejection such as: What should I do when a good Documentation change is rejected?

8
  • 1
    "Someone please sanity-check my assumptions: " Yes, that's how it works. Just like an edit to a post, edits to documentation show any changes highlighted in red or green.
    – Kendra
    Feb 23, 2017 at 15:50
  • As a side note, do you have any examples you can link to for this?
    – Kendra
    Feb 23, 2017 at 15:51
  • @Kendra now my queue is empty and I am not sure how to go back to things I accepted. I'll try to find them. (but later... running to work now) Feb 23, 2017 at 15:54
  • (For when you have time) You can find reviews you specifically have done on your Stack Overflow profile. Under the "Documentation" tab, you should be able to find them pretty quickly.
    – Kendra
    Feb 23, 2017 at 15:55
  • 1
    Alternatively we can put a huge warning saying that YOU MUST SKIP REVIEW ITEMS THAT YOU DON'T UNDERSTAND (with that exact formatting).
    – SE is dead
    Feb 23, 2017 at 15:58
  • Yes, under the buttons of "Approve Reject Skip" a short description, in which cases to use what would be helpful.
    – Myonara
    Feb 23, 2017 at 16:09
  • heh, in the same way reviewers often approve changes that shouldn't be approved.
    – Kevin B
    Feb 23, 2017 at 20:18
  • We did some work to clarify the review page. I'm not sure if it fixed this particular problem, however. Sep 26, 2017 at 20:15

0

Browse other questions tagged .