13

Currently the R topic is a mix of base R documentation and package documentation. Its seems as though most people are posting package specific documentation within the R tag. However, separate tags exist for the individual packages (as with SO proper).

For example:

and

What is the right rule here? Do libraries/packages belong within the tag of a language as topics, or as a separate tag?

1
  • 2
    As an aside, Feel free to visit the R Public chatroom to discuss about any SO docs related to the R Programming language. Commented Jul 26, 2016 at 20:21

4 Answers 4

13

My (strong) opinion is that libraries belong in their own, respective library tags. The tools to move them there are clunky right now, but by and large, that's where I believe they should live.

The language can survive without the library, and if you're looking for documentation related to the library, you very likely already know the language you need to use with it, so I see no reason for the two to live together.

0
11

As far as I am aware libraries and languages need to be in separate tags. This means that ggplot2 should be its own tag, along with its own set of topics and examples. Just as R should be its own tag, along with its own set of topics and examples.

The examples you list here needs more jQuery. jQuery is a library and should absolutely be separated from JavaScript which is the language it was written in. There are many more examples of this happening as well, but I think that the JavaScript/jQuery instance is one of the more prominent ones.
(feel free to read jQuery as Angular in this paragraph)

4
  • 5
    followed your instructions, but then your answer needed more jQuery
    – Chris
    Commented Jul 26, 2016 at 20:20
  • There are a bunch of examples using jQuery, in the JavaScript tag.
    – Cerbrus
    Commented Jul 29, 2016 at 22:15
  • "Your search - site:http://stackoverflow.com/documentation/javascript/ jquery - did not match any documents." -Google
    – Travis J
    Commented Jul 29, 2016 at 22:45
  • libraries and languages need to be in separate tags -- Not unqualified; I don't think there's any reason to document the Python standard library separate from Python.
    – Zev Spitz
    Commented Feb 14, 2017 at 7:57
3

Preferably, I'd see an extra "level" of categorisation:

Keep the "language" tags, as they are.
In there, keep the topics with their examples as they are.

However, move "library" tags (including things like Node.js, which isn't really a library) to be a "child" of their respective language tag.

Visually, this could be represented as a list of "child tags" in the language's dashboard, and a link back to the "parent", in the child's dashboard.
For the rest, the child dashboard should remain the same.

Searching for topics in the parent dashboard could (optionally) include child tags.

The advantage is that, semantically, every topic is categorised under the language it's written in. However, there will still be the "library-specific" separation.

1
  • 2
    This wouldn't help for language-independent libraries, such as .NET Framework, or REST APIs.
    – Zev Spitz
    Commented Feb 14, 2017 at 7:52
2

I would suggest that a library or API should be documented / tagged together with the language when it meets both the following criteria:

  1. The library/API is only consumable from that language
  2. The library/API is always available from that language

Examples:

  • Javascript built-in objects -- Date, Regex, Math
  • C, C++, Python standard libraries
  • VBA Collection object

Examples which don't match #1:

  • REST APIs — cannot be associated with a given language, because they are equally accessible from any language which supports web requests
  • ASP.NET, WPF, Winforms, LINQ extension methods1, and the entire .NET Framework should always available to any given .NET language; but they are equally available to all .NET languages
  • ActiveX object models (e.g. MS Office object models, WMI, WIA, DAO, ADO) are equally consumable by all Automation-supporting languages

Examples which don't match #2:

  • The DOM is sometimes available to Javascript, and sometimes not
  • Virtually all Javascript libraries — sometimes they will have been loaded into the environment, sometimes not
  • ActiveX object models (e.g. MS Office object models, WMI, WIA, DAO, ADO) are not guaranteed to be available in every environment in which the Automation-supporting language can be used

1. The LINQ keywords which the compiler converts into method calls are part of the language, and should be documented with the language.

6
  • The built-in objects of JavaScript are part of the language (e.g., the Date constructor, defined in ECMAScript 2015), so that example may be a bit off... Agree with the rest. Commented Feb 14, 2017 at 15:19
  • @MikeMcCaughan They may be part of the ECMAScript specification, but not part of the language -- the keywords, operators, statements and other syntax bits of the language. From the perspective of the language user, both built-in and non-built-in objects/functions are consumed in the same way -- let dte = new Date(); let instance = new MyClass();. Consider regular expressions, arrays, and functions -- each of these has a dedicated syntax besides for new Array(), new RegExp(), new Function(); this syntax is part of the language.
    – Zev Spitz
    Commented Feb 14, 2017 at 16:03
  • @MikeMcCaughan Also, I'm not sure why these objects should be considered part of the language; how are they different from the C standard library?
    – Zev Spitz
    Commented Feb 14, 2017 at 16:07
  • I have no experience with C nor its standard library. All I know is that if there's an implementation of ECMAScript, it has those objects. I don't really care if it's pedantically "part of the language", only that, since it's always present (and required to be present) when using the language, I need to know about them. I mean, no one talks about the "JavaScript standard library", except to name their version of a utility function library that... Commented Feb 14, 2017 at 16:21
  • Umm... You realized Documentation was removed right? I'm not sure why you'd edit an answer (bumping the question to the home page) about it... Commented Jun 27, 2018 at 12:40
  • @MikeMcCaughan Because I think the same rules apply when identifying concerns for tag creation, and I wanted to clarify the language I was using here.
    – Zev Spitz
    Commented Jun 27, 2018 at 12:46

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