5

I'm seeing a lot of topics in Documentation like this one on the DOM. Because the DOM is not a particular function or code concept, it does not lend itself well to examples. Instead, the "Examples" section is being used like this to provide general information.

I know the obvious response is "Put it in Remarks instead!" but

  • The Remarks section must be edited as a whole and can be changed on a whim
  • Some topics really are purely informational and as such don't really have "Examples" or "Syntax", and to call this information simply "Remarks" belies the nature of the topic.

What is the solution here? Should Remarks be given multiple up- and down-votable entries like Examples to alleviate this? Should Remarks be renamed? Or is Examples really the place to put such information?

(Or...is StackOverflow Documentation not the place for such topics in the first place?)

2
  • 1
    Depends what SO were expecting us to document (which still isn't clear) - if it's meant to be just for programming languages (which is what the terminolgy and UI imply) then we wouldn't have a tag for DOM, we would have examples of how to work with DOM in other language tags. Commented Jul 29, 2016 at 14:58
  • DOM can have a lot of examples and topics, on how to manipulate the DOM for example, which should not be in the JavaScript tag. I don't think those two introduction examples are bad, but surely they're not exactly examples. You can follow this disucssion if you're insterested in the DOM tag vs JavaScript tag thing: meta.stackoverflow.com/questions/328778/… Commented Jul 29, 2016 at 15:09

0

Browse other questions tagged .