17

There is an issue with narrowly defined tags duplicating the content of topics from broader tags. This is visible in places where a framework will show up as being documented in both the language it was written in, and also in its own tag. This was largely solved with the consensus being to place all of the content in the framework tag.

However, while that solution is good for frameworks, it does not work well with language features; for example, LINQ. The documentation in the C# tag for LINQ is fairly high quality at the moment, but unfortunately there is another LINQ topic that is very low quality. Not only does this tag have duplicate content with regards to naming, but the examples are often flat out incorrect in their description of the feature.

Moreover, language features tend to be rather narrow in their scope. While language feature tags work well at Stack Overflow, in Documentation using them to create examples seems to be problematic, especially in this instance.

Unfortunately there is nothing that can be done as a user, even with all of the privileges unlocked, to address this tag (or this situation in general).

What approach should we be using to address these types of situations in Documentation? Do we need additional tools (features) for assist in fixing this problem, or is the existing toolset sufficient?

19
  • 5
    I read the consensus from that link as being that individual libraries/frameworks should be documented separately from the language, not that everything in the library/framework should be grouped together. LINQ should be documented in .NET, since it exists as libraries from that framework, completely separate from C#, or in its own tag, if the .NET tag grows too big with LINQ examples. Commented Oct 6, 2016 at 20:24
  • 2
    There are a minimal set of language-specific keywords relating to LINQ -- select (C#), Select (VB.NET), Aggregate (VB.NET) for example -- that leverage specific LINQ signatures / features. These need to be under the language tag.
    – Zev Spitz
    Commented Oct 6, 2016 at 21:56
  • I am curious to know what you found to be incorrect within the linq tag. Unless the C# [LINQ] topic is overflowing with examples of method usage, which could be easily found on MSDN?
    – Zev Spitz
    Commented Oct 6, 2016 at 22:18
  • 2
    LINQ is actually documented in a third place, besides the two you've mentioned -- within .NET Framework. But there is no conceptual documentation there at all; nothing more than can be found at MSDN.
    – Zev Spitz
    Commented Oct 6, 2016 at 22:20
  • 2
    And there's also VB.NET LINQ.
    – Zev Spitz
    Commented Oct 7, 2016 at 1:39
  • Incorrect? Jeez, let me count the ways. The benefits of deferred execution mentions operators and chaining, neither of which are benefits provided by linq (operators doesn't even make sense in that setting). The code conventions for styling is Java-esque, and uses var waaaay to often when the actual type should be used. There is no prose, and the final example doesn't even demonstrate deferred execution. This is just one example. The entire set of content there suffers from these same types of problems.
    – Travis J
    Commented Oct 7, 2016 at 18:49
  • @TravisJ The benefits of deferred execution mentions operators and chaining In the four examples under "Query execution modes", the word "chaining" does not appear, and the only usage of the word "operator" refers to "standard query operator", as in "The standard query operators are the methods that form the LINQ pattern.".
    – Zev Spitz
    Commented Oct 8, 2016 at 19:21
  • @TravisJ neither of which are benefits provided by linq The so-called "benefits of deferred execution" are not of LINQ, but of "deferred execution" === "the query doesn't hold the values" -- 1) the query doesn't hold the values, so I can modify the query before actually getting the values, and 2) the query doesn't hold the values, so I can modify the underlying data source and the query will be against the new data.
    – Zev Spitz
    Commented Oct 8, 2016 at 19:22
  • @TravisJ (operators doesn't even make sense in that setting) Methods matching the LINQ pattern are referred to as standard query operators.
    – Zev Spitz
    Commented Oct 8, 2016 at 19:22
  • 1
    @TravisJ The code conventions for styling is Java-esque ... uses var waaaay too often Are stylistic conventions a reason to dismiss examples as low quality, especially when those coding conventions are not universally accepted, to put it mildly?
    – Zev Spitz
    Commented Oct 8, 2016 at 19:22
  • @TravisJ The code conventions for styling is Java-esque I've never programmed in Java so I'm not sure what you mean.
    – Zev Spitz
    Commented Oct 8, 2016 at 19:23
  • 1
    @TravisJ uses var waaaay to often I'm partial to var as it allows focusing on what the code is trying to do instead of getting hung up on the types involved. This is admittedly my own person preference. But the vaunted high-quality C# LINQ documentation also uses var about half the time, and not for anonymous types, but for things like var chars = new List<string>() { "a", "b", "c", "d" };
    – Zev Spitz
    Commented Oct 8, 2016 at 19:23
  • @TravisJ There is no prose The topic entitled Query execution modes was about 50% prose.
    – Zev Spitz
    Commented Oct 8, 2016 at 19:23
  • @TravisJ the final example doesn't even demonstrate deferred execution Are we talking about "Streaming mode (lazy evaluation) vs non-streaming mode (eager evaluation)"? Because that actually does use deferred execution, although the point is to demonstrate streaming / non-streaming mode. Or are we talking about "Deferred execution vs immediate execution", whose last code example does indeed demonstrate non-deferred execution.
    – Zev Spitz
    Commented Oct 8, 2016 at 19:24
  • @TravisJ Further, IQ versus IEN shows bad practice with regards to connection threads. I assume you mean the lack of using (although your usage of "connection threads" to mean both ADO.NET connections and HTTP requests is rather odd) and it has been fixed (I initially didn't want to detract from the simplicity of the example).
    – Zev Spitz
    Commented Oct 9, 2016 at 19:33

1 Answer 1

1

TL;DR

Specifically regarding LINQ documentation, I suggest the following:

LINQ can be separated into two components:

  1. A set of language keywords / features1, which should be documented with the language

  2. Extension methods on IEnumerable<T> and IQueryable<T>, which should be documented in the separate LINQ tag, or with the .NET Framework, depending on how much content there is.

In addition, there is also:

  1. Conceptual documentation on LINQ, which should certainly not be documented with a specific language, but as above (2) — in the separate LINQ tag, or with the .NET Framework.

Currently, it will be rather difficult to migrate the language-neutral content from C# LINQ to either LINQ, or to LINQ within .NET Framework, because of the sheer number of examples in C# LINQ (47).


Long version

Language keywords

C#, VB.NET and F# each have a set of language keywords for writing queries, which the compiler translates to calls to matching methods (either extension methods or instance methods, which take an appropriate delegate / expression tree).

These keywords are unique to the language (e.g. VB.NET has some keywords which C# doesn't have), and thus should be documented as part of the language. At most, the compiler's translation should be noted in the documentation.

But examples of LINQ methods that do not have a corresponding language keyword (ToList, Average in C#, Single outside of F#'s exactlyOne) inevitably show nothing more than how to call these methods in the language, with various parameters. There is no reason to document them with the language.

Extension methods

Since the extension methods defined in System.Linq.Enumerable and System.Linq.Queryable are part of the framework, perhaps they should be documented with the framework (either in a language-neutral manner, or with examples in multiple languages).

Conceptual documentation

What Documentation can provide, is a set of examples for LINQ-related conceptual topics:

  • The concept of keyword syntax which compiles into method calls and delegates / expressions
  • IEnumerable<T> vs IQueryable<T>, or what does cannot map x to canonical method mean?
  • Query execution modes Method's manner of execution - immediate / deferred non-streaming / deferred streaming (MSDN)
  • Method chaining

1. There are other language features that have been added to support LINQ, but are not used only for LINQ (e.g. var in C#, or lambda expressions). These should not be documented with LINQ at all.

5
  • No. The bullet points you list are already covered in depth in the c# linq queries topic. The content in the linq tag is low quality and is duplication. "Execution mode" refers to executing a query in parallel. Simply introducing incorrect terminology because it sounds good is part of the reason this entire tag is low quality.
    – Travis J
    Commented Oct 7, 2016 at 18:57
  • @TravisJ The bullet points... Does that mean you agree with everything until the bullet points -- that the only documentation under C# linq should be of the C#-specific LINQ keywords, but documentatino of method calls and concepts should be in a language-neutral location, either under .NET Framework, or under a separate LINQ tag?
    – Zev Spitz
    Commented Oct 8, 2016 at 18:36
  • @TravisJ already covered in depth in the c# linq queries topc Not the point. All these are topics are not C#-specific, but apply in theory to all .NET languages, and should be under .NET Framework, or under a separate LINQ tag. (Even though not all languages have LINQ keywords (1), nor do all languages support extension methods (4))
    – Zev Spitz
    Commented Oct 8, 2016 at 18:37
  • @TravisJ already covered in depth in the c# linq queries topic IQueryable<T> is not mentioned there, nor is the distinction between streaming and non-streaming methods.
    – Zev Spitz
    Commented Oct 8, 2016 at 18:37
  • @TravisJ "Execution mode" refers to executing a query in parallel. Simply introducing incorrect terminology because it sounds good... Then the right term should be manner of execution instead.
    – Zev Spitz
    Commented Oct 8, 2016 at 19:34

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