3 ms·

Does anyone else find it a bit problematic that documentation, which should mainly be descriptive, is taking an ideological stance? It's one thing to describe k

Does anyone else find it a bit problematic that documentation, which should mainly be descriptive, is taking an ideological stance? It's one thing to describe known bugs around an implementation, but reading the MDN docs on accept-header, it's pretty clearly advocating against using accept-header. How can a web-reference justify recommending against standards? I understand it's not meant as the canonical reference doc, but that's pretty much how it ends up being used and I think Mozilla should be more conscious of the position of its docs. (I personally find MDN much easier on the eyes and useful with its compatibility tables and examples)

kristopolous 9y ago
Although not obvious, MDN is a wiki with a pretty level-headed and healthy community. I've done numerous edits that were well-received so I say feel free to change it.
- cooper12 9y ago
  Ah, that is a reasonable suggestion. I would but unfortunately I don't feel technically competent to do so. (I'm more the type of programmer who would rely on MDN rather than write anything on it) It's too bad there's no discussion page like other wikis have. Under the feeback tab in the navbar, there is "report a content problem", but that requires filing a bugzilla. Don't get me wrong, overall I'm quite satisfied with the quality of MDN (it's so much better than w3schools which I was using before), it's just the tone of this particular article.
  - ubernostrum 9y ago
    MDN articles aren't supposed to be just flat descriptions of "Feature X does Y. To use feature X, place the following code in..." MDN is supposed to be an educational resource that can teach people what different bits of technology are for, when and why they can be used, etc., and so it's appropriate -- if there is a common problem with something -- to mention the problem. And though I didn't write that article (but I did work on MDN's software platform during my time at Mozilla), I largely agree that Accept-Language simply doesn't work, and some other sort of in-page UI is far more reliable. There's a reason why MDN will do content negotiation, but also shows a drop-down of languages an article is available in and uses language identifiers in URLs, after all.
    - kristopolous 9y ago
      The description on MDN does fairly accurately describe the state of the world. It could be read as advocacy but I don't think that was the intention, maybe the word "describe" is better than "justify". So I changed it to: "MDN attempts to describe why Accept-Language ought to be ignored. The reasons are fairly weak when the..." Which reframes MDN as a reporter instead of an advocate.

kristopolous 9y ago

Although not obvious, MDN is a wiki with a pretty level-headed and healthy community. I've done numerous edits that were well-received so I say feel free to change it.

cooper12 9y ago
Ah, that is a reasonable suggestion. I would but unfortunately I don't feel technically competent to do so. (I'm more the type of programmer who would rely on MDN rather than write anything on it) It's too bad there's no discussion page like other wikis have. Under the feeback tab in the navbar, there is "report a content problem", but that requires filing a bugzilla. Don't get me wrong, overall I'm quite satisfied with the quality of MDN (it's so much better than w3schools which I was using before), it's just the tone of this particular article.
- ubernostrum 9y ago
  MDN articles aren't supposed to be just flat descriptions of "Feature X does Y. To use feature X, place the following code in..." MDN is supposed to be an educational resource that can teach people what different bits of technology are for, when and why they can be used, etc., and so it's appropriate -- if there is a common problem with something -- to mention the problem. And though I didn't write that article (but I did work on MDN's software platform during my time at Mozilla), I largely agree that Accept-Language simply doesn't work, and some other sort of in-page UI is far more reliable. There's a reason why MDN will do content negotiation, but also shows a drop-down of languages an article is available in and uses language identifiers in URLs, after all.
  - kristopolous 9y ago
    The description on MDN does fairly accurately describe the state of the world. It could be read as advocacy but I don't think that was the intention, maybe the word "describe" is better than "justify". So I changed it to: "MDN attempts to describe why Accept-Language ought to be ignored. The reasons are fairly weak when the..." Which reframes MDN as a reporter instead of an advocate.