2

I submitted a change recently to one of the Docs for C# (which as the title implies, was rejected). Perhaps the two people that rejected my change request were right in doing so, and I could have improved what I had already written - but the responses that the two users left me was utterly useless for specifically telling me what was wrong.

Here's what the first and second read:

Rejected by User 1

Contains factually incorrect information. The example is totally useless.

Rejected by User 2

Other: Thanks Captain Obvious!.......

Receiving rejection information like this is borderline meaningless - if the first user had indicated what part was wrong, I would've at least been able to correct whatever it was. The second user's answer arguably isn't even a reason for rejection.

It would be nice if there were either more specific things to select as categories for rejection, or otherwise requiring approval or rejection to actually have some thought put into them. Otherwise, instead of encouraging users like me to improve on what was wrong in our documentation, it tells us not to bother since the community will drop red X's almost arbitrarily.

In short: Rejections miss their ability to be constructive by not including enough information in their categories and by not having users specify what's actually wrong.

7
  • 1
    I found the review. It's here. Just in case the context matters.
    – Laurel
    Commented Aug 3, 2016 at 14:27
  • I wanted to hide the usernames (thought I doubt anyone would say anything to them directly), but if it doesn't make a difference yes, the specific changes and names are available there. Commented Aug 3, 2016 at 14:31
  • 1
    Well, they could add support to @ comment any reviewers under any examples in the proposed edit, to discuss it. I think the real problem is that you don't have a better venue to discuss the proposal with others in your tag and come to some consensus on its value or where it needs improvement meta.stackoverflow.com/q/329686
    – Frank
    Commented Aug 3, 2016 at 14:37
  • 1
    Well, you could try going onto chat. There are a few different rooms dedicated to documentation review including one called Documentation Review :). Commented Aug 3, 2016 at 14:42
  • 1
    @Frank Yeah, one of the questions in the link chain describes it well - it's almost a shame that given SO's otherwise nice design of being able to comment on both questions and answers that the review system doesn't function similarly. One of the biggest disconnects between the two systems is that unlike QA, documentation is really only a one-way communication. Commented Aug 3, 2016 at 14:42
  • @MikeMcCaughan this is nice for the current size of documentation, but obviously isn't very official or as organized as a more concrete solution. Commented Aug 3, 2016 at 14:44
  • Well the chat linked at the top of every Documentation page seems pretty official. And you tagged this post discussion, not feature-request so I assumed you were looking for help, not a formal way of doing things. Sounds like you wanted to vent though, which, when it comes to Docs, is wholly justified. Commented Aug 3, 2016 at 14:50

1 Answer 1

2

The first one appears to be some sort of variation on the canned rejection reason:

  • incorrect
    Includes factually incorrect information.

The second one appears to be a blatant violation of the Be Nice policy:

Don't be a jerk. These are just a few examples. If you see them, flag them:

  • Name-calling. Focus on the post, not the person. That includes terms that feel personal even when they're applied to posts (like "lazy", "ignorant", or "whiny").

It is possible to discuss proposed changes. If you look at any review, you should see an "add a comment" link at the bottom of each changed section. If the reviewers wanted to, they could point out what's wrong, and you could @ping your reply.

As the comments have said, chat may be the most helpful way of getting feedback. That way, you will encounter more people, many of which are willing to help. Asking also shows that you are open to criticism, which is great.

3
  • Apologies for not noticing the comments for each section - if I comment there will it send notifications to reviewers? Commented Aug 3, 2016 at 15:04
  • 1
    @JeremyKato I think so.
    – Jed Fox
    Commented Aug 3, 2016 at 15:10
  • 1
    @JeremyKato I'm not sure how it works entirely. It does work if the reviewers commented, but that isn't the case here. (Keep in mind Docs is new for everyone, including me.)
    – Laurel
    Commented Aug 3, 2016 at 15:11

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