12

As I asked in the comments in this change request, what is on-topic and what is off-topic as far as examples explaining how to use third-party libraries on Documentation? From my comment: "[W]here [do we] draw the line on what should be included in Documentation and what should not[?] Are other multiplexers from other libraries on topic? Are examples of a library that someone made on Github yesterday that has 1 star on topic?"

3 Answers 3

14

Language tags should document ... the language. Not libraries. Not APIs that are commonly used with the language.

For instance, right now the JavaScript tag is a mess of actual language features (like Classes or Arrays) and other tangentially related things like DOM-related features like 2D Canvas and, well, DOM, and Browser-related features like Web Cryptography and Web Storage.

The language should be documented as it is, not the environment in which is is used. Otherwise, continuing with the example, JavaScript will contain everything under the Node.js umbrella, all of the HTML5 APIs, and maybe the attempts to embed JavaScript in devices, because, hey, it's JavaScript.

19
  • 8
    Where else would you document array functionalities, and dom-related JavaScript features, if not in JavaScript? Node.js is a completely different subset, and libraries also shouldn't be added to the JS documentation, but when you say "I know JavaScript", everyone assumes you're familiar with DOM manipulation.
    – Cerbrus
    Commented Jul 23, 2016 at 10:43
  • 1
    The DOM should be documented in the DOM tag. The note about classes and arrays was meant to be the "good" to be contrasted against the following "bad" things. I agree that people make assumptions. The question we face on Documentation is whether we document assumptions or reality. I prefer the latter. Commented Jul 23, 2016 at 16:17
  • 1
    Isn't the DOM well enough documented on MDN? I thought the mission for documentation was to improve docs that are otherwise not good enough and not to increase fragmentation?
    – ivarni
    Commented Jul 23, 2016 at 16:21
  • @ivarni that's a different question than the one this post answered. Commented Jul 23, 2016 at 16:49
  • It's a reply to a comment, not the answer. I see I forgot to tag it and it's too late to edit.
    – ivarni
    Commented Jul 23, 2016 at 16:53
  • Well to respond to the comment, sure, the DOM is well documented, although I'd say the examples are not always great. And apparently it's all about examples on Docs... Commented Jul 23, 2016 at 16:56
  • "The language should be documented as it is, not the environment in which is is used." While I agree with this in general, in the specific case of JavaScript, I have to disagree. 99% of all users of JavaScript are using it in a browser. Oh sure, there are some standalone apps that use it as their scripting language of choice. But for the vast majority of users, JavaScript == browser. From a practical perspective, it seems absurd to separate JavaScript documentation from the environment for which it was created. Commented Jul 23, 2016 at 17:17
  • @NicolBolas That's a valid point (though I doubt the actual number is 99% you're probably right about the vast majority part). But then, how many javascript users today actually interact with the DOM directly? I'd say "few" since I don't have numbers but from my experience most devs are using some framework that abstracts the DOM away so how useful is it really to document it under the Javascript Language topic?
    – ivarni
    Commented Jul 23, 2016 at 17:30
  • My main gripe right now is the sheer number of topics under any given tag. It's a mess, like this answer points out, and it's hard to get an overview of actual language topics because they're intermixed with stuff like DOM features and browser APIs. It makes it hard for someone to find what's already documented and what's not.
    – ivarni
    Commented Jul 23, 2016 at 17:32
  • 1
    @ivarni: "it's hard to get an overview of actual language topics because they're intermixed with stuff like DOM features and browser APIs." To me, the best way to fix that is to give us real ways to categorize things into more than just topics and examples. Commented Jul 23, 2016 at 17:35
  • @NicolBolas Yes! That's what I want too. But I think we should still be able to have a link to that "sub-section" or whatever it would be called from the actual tag on SO main. To me good documentation is good if it's both well written and easy to find. With peer-review I think SO documentation can eventually provide the first but as it is now can't possibly provide the second.
    – ivarni
    Commented Jul 23, 2016 at 17:40
  • @NicolBolas You may very well believe that 99% of JavaScript occurs in a browser, or perhaps that's hyperbole. I think that as JavaScript matures, there will be more an more places where JavaScript will be used outside of the browser. It's already got the incredibly fast-growing Node.js environment. Commented Jul 23, 2016 at 20:46
  • @NicolBolas Additionally, with the advent of Web Assembly, other languages will be able to access the DOM and be used with browsers. Why limit examples for the DOM to only being written in JavaScript? Commented Jul 23, 2016 at 20:48
  • You should totally drop that and use jQuery... and I'm not joking!
    – Braiam
    Commented Jul 24, 2016 at 1:30
  • 1
    Node.js Is a topic on it's own, because it's a completely different topic. It's a server-side language that has a crapload of extra config / functionalities. Every single JavaScript documentation / tutorial site out there explains DOM features. It's a integral part of the language. There is absolutely no point in splitting out DOM from the JavaScript topic, other than adding more confusing separation. Node on the other hand is simply too large not to be a topic on it's own.
    – Cerbrus
    Commented Jul 24, 2016 at 16:04
4

(Disclaimer: I'm the creator of the linked change request.)

To me, this issue is fairly clear. Documentation needs to be useful, and in order for it to be useful, it needs to provide documentation for the topics people need.

Many small libraries and addons don't warrant their own sections under Documentation. They're simply not large enough. Pircbot, the Gorilla Toolkit, and LuaSocket are three examples I'd pull off the top of my head. Creating an entire section for a library as small and single-track as LuaSocket would be absurd - it would have one page, and that would be it. There simply wouldn't be more to add, even if someone wanted to.

But if we want this feature to be useful, it needs to document commonly-used libraries somewhere. That's basically the entire point - to help people by providing examples of how to do common tasks.

If someone creates an extra page under a topic for a library that's never used - that's fine. Maybe some day someone will search and find it, or maybe it'll never come up again. But barring all third party libraries prohibits an entire class of documentation information that is both useful and pertinent to a developer's searches.

If a library or project, like OpenCV, gets large enough, then it probably warrants separating off. But if it's too small to fit on its own, I'd rather have good documentation under the language documents than leave it off entirely - particularly for commonly-used tools for their specific purposes, like the ones I mentioned above.

5
  • There's got to be a reason there are requirements for how popular a tag is before it can have a topic on documentation and I would suspect that is because there is no point in SO maintaining documentation for libraries that hardly anyone use. If there was a need for documentation here there'd be enough activity in the tag for it to have its own topic. If not, well, then that documentation should rather sit in the README.md at GitHub than pollute the namespace of the language its written for.
    – ivarni
    Commented Jul 23, 2016 at 16:15
  • @ivarni I think the error here is in thinking that documenting third party libraries will somehow detract from the documentation of core language features, which is simply not the case. A well written third party document wouldn't "pollute" Documentation.
    – user1131435
    Commented Jul 23, 2016 at 16:22
  • "Creating an entire section for a library as small and single-track as LuaSocket would be absurd" I disagree. LuaSocket is not small. It may be "single-track", but it's got lots of features. To truly document LuaSocket would require dozens of topics. Commented Jul 23, 2016 at 17:13
  • 1
    @Emrakul I tend to disagree but the problem might simply be that we don't have the option to nest examples. If there could be a sub-topic called LuaSocket and we could add examples under that then it would alleviate some of the problem, but if we need "dozens of topics" to do it and they would be mixed with everything else then it makes for a very cluttered frontpage. I don't think it scales. You'd have a hard time finding anything unless you already knew where it was.
    – ivarni
    Commented Jul 23, 2016 at 17:38
  • 1
    I can see no actual problem caused by a subject -- such as your example LuaSocket -- having only one sub-item.
    – jscs
    Commented Jul 24, 2016 at 17:21
-1

IMHO we should include the examples of small libraries unless they have their own topics or if we are thinking about drawing the line stictly, create topics for everything. But if we create a new topic for every library, we'll need someone to maintain it dedicately too.

So, the best option is to allow libraries to be included in the language/platform topic. This doesn't mean we should put Node.js in JavaScript, because Node.js has it's own topic. But we can include Express in Node.js, until Express have it's own topic. Same with Passport.

Another example would be with ButterKnife. It'll be gross misuse of resources, if we'll create it's own topic separate from Android. So does it mean we should exclude ButterKnife altogether, provided how useful it is in saving a lot of time of developers.

That also mean we should have some way to transfer examples to new topic whenever it gets created.

3
  • 1
    You're using the word "topic" but I think you mean "Tag", since that's the top-level grouping in Docs. "Topic"s are the second level.
    – jscs
    Commented Jul 24, 2016 at 17:14
  • Yeah, that's what I meant. Documentation lingo is still not clear to me.
    – 0xC0DED00D
    Commented Jul 24, 2016 at 17:43
  • 1
    Nor to me, honestly!
    – jscs
    Commented Jul 24, 2016 at 17:43

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