43

A few days ago I stumbled across the documentation section for the first time. I really liked the idea of having the users of language write the documentation instead of the developers of the language. So I recently added some changes for an improvement request in JavaScript, but it turned out that someone had undone my changes (and a few more) recently.

Now that I finally got some time to look into it changes in detail, there are a bunch of problems that are hard to ignore.

1. The changes

As I mentioned, total three sets of changes were undone. So a lot of content was being removed from the page. Here are a few samples of it:enter image description here

First problem is the rewording of,

An easier approach for some would be to use an existing JavaScript library.

To,

The best approach would be to use an existing JavaScript library.

This is primarily opinion based. In general it would be best to use a JavaScript library, but there can be cases where it is not the best option. What is someone is targeting for an enterprise application, where the audience is only Chrome and IE users. In such cases, I would prefer to use the browser detection based on user agent, rather than adding a library.

Another problem is the first conditional block of the example. Originally it was:

if (bowser.msie && bowser.version >= 6) {
    alert('IE version 6 or newer');
}

It was modified to:

if (bowser.msie && bowser.version <= 6) {
  alert('IE version 6 or newer');
}

Note the change in the condition from >= 6 to <= 6. I believe that the original example was correct, based on the documentation on Git repository, but I might be wrong.

In the next example, my changes were completely removed. I had elaborated on the example as per the improvement request. I think, if my changes were bad, and if someone is removing them, they should at least be adding their own changes to address the original problem, i.e. the lack of clarity in the given example.enter image description here

Finally, one line from the remarks section was removed, that mentioned Modernizr - as a feature detection library. The strange part is that the change comments are as follows (emphasis mine):

A change is being rolled back because: this rewording does not handle the improvement request. There isn't even a mention of modernizr, one of the most widely used feature detection libraries!

Why would you remove the mention of something that you consider to be the best?!

2. The Approvers

There are three approvers, by ID:

  1. User 7776603, who has Python as the top tag, and JavaScript nowhere to be seen in the tags on his profile (!)

  2. User 7522548, who has PHP as the top tag, and JavaScript with a total score of 3

  3. User 5077564, who has PHP as the top tag, and JavaScript with a total score of 1.

The question is, are they really qualified to approve changes in JavaScript? Shouldn't someone with better reputation be approving JavaScript changes?

And, I'd be honest, I am not best qualified either. My top tag is JavaScript, with a score of 3. :)

Finally

My questions are,

  1. Are the changes done by User 1675954 really constructive?

  2. Are the approvers qualified to approve this particular change? If not, can anything be done to avoid such cases?

16
  • 18
    "There are three approvers, without mentioning their names:" kind of moot when the links in your post have the names..No need to say this IMO..Or remove those links if you really dont want to mention them
    – Suraj Rao
    Jun 17, 2017 at 4:39
  • 5
    Well, if someone's curious enough, they will be able to find out the approvers through the change link. So I thought to reduce the burden of adding one extra click. :) Jun 17, 2017 at 4:41
  • 2
    I'm not sure what happened here, but I should note that the user who rolled back the changes also submitted improvement requests on the topic. I wonder if they are dissatisfied with the changes? I also wonder if it wasn't entirely clear to the reviewers that this was a rollback. In any case, I'd suggest rolling back to the previous version and see if reviewers agree that's a better version. Jun 17, 2017 at 5:13
  • Okay, I just submitted the reverted version, but added in the introduction - with some changes (which I couldn't resist). But I am still uncertain as to whether the same user cannot undo these changes - with help of three reviewers - who may not understand the domain sufficiently! Shouldn't there be some restriction on who could approve/reject changes of a particular topic based on their participation on a particular tag? Jun 17, 2017 at 8:14
  • 8
    Reputation is not an end-all indicator of someone's expertise. e.g. someone could have 30 years experience in a field, but not have an SO account (and thus have 0 rep). It's really up to the user to decide if they can review an edit. Jun 18, 2017 at 10:43
  • 9
    I agree that reputation cannot be the sole indicator of someone's knowledge. But I don't know a better one. Also, we do have a constraint on new tag proposals - i.e. only the users having at least one positively scored answer in given tag can be a committer or backer. Why should/could we not have such a restriction for reviews? Jun 18, 2017 at 16:15
  • 7
    @JornVernee by that logic there shouldn't be a rep-req for any action on SO. Yes, low rep doesn't mean you don't know a technology, but some rep at least show that you know something about it.
    – Matsemann
    Jun 18, 2017 at 19:41
  • @NisargShah Not all edits require knowledge of the subjects. A lot of edits fix formatting issues or spelling mistakes, or they add reference links. The reviewer can best decide if they can review an edit or not. Jun 18, 2017 at 19:58
  • 4
    @JornVernee In theory you are correct, but in practice reviewers often accept major (content-related, as opposed to relatively minor formatting / spelling edits) edits, which are outside their areas of expertise. (A thought -- perhaps the review process should differentiate between major and minor edits, and would major edits to be reviewed only by high-rep users in that particular tag.) Also, why are reviewers any less human than documentation authors, who require checks before their edits are accepted?
    – Zev Spitz
    Jun 18, 2017 at 21:30
  • 1
    @ZevSpitz I guess I can only speak for myself, but I skip any review that I can't verify. -- The reviewers are indeed human too, the fail-safe there is that there are multiple (though it's not perfect). Jun 18, 2017 at 21:52
  • 22
    @JornVernee Your view on reputation and Docs reviewers does not match up to reality. It's great that you skip reviews you don't understand (someone listened!) but most reviewers do not. I cannot count how many times I have reverted junk written by someone and approved by 3 low rep users, sometimes without a score in the tag.
    – Machavity Mod
    Jun 19, 2017 at 1:34
  • This is why documentation never will work out well. There is too many if conditions.
    – JonH
    Jun 19, 2017 at 15:38
  • @JonH First of all, I don't think complexity correlates to or causes failure. Because, if that were true, the only form of life to ever survive would be Amoeba. Second, even if documentation is getting complicated, it is improving with each additional if condition. I personally hope that documentation works out. Probably because nobody would let me improve an example on MSDN, for example, but here I can do that! Jun 19, 2017 at 16:59
  • Documentation should be written without making inferences or opinions. State the facts and nothing more. Documentation is about how to use whatever is being documented in a generic way, not any specific usage. Also, having high scores in Javascript and/or a top poster in a language does not make a person an expert at writing documentation.
    – Gewthen
    Jun 19, 2017 at 17:08
  • 2
    remove rep from it. no longer will people contribute to it for rep.
    – Kevin B
    Jun 19, 2017 at 22:06

0

Browse other questions tagged .