15

Not long ago, a documentation topic for Java 8 features was requested, and that caught my attention. Should we really be making topics that aggregate new features in a language?

I can only think of drawbacks when doing this. Such features usually deserve their own documentation topic, and they will then have a range of language versions reflecting that. One can (in theory) retrieve a list of all documentation topics that only apply from that version onward. It is also debatable whether fetching a list of new features in a language is a requirement for SO Documentation, but the means to perform this query on the user interface can be added in the future if it turns out to be something reasonable to have.

Furthermore, it appears that the JavaScript tag has one for ECMAScript 2015, but it only covers a very small part of what was introduced in the new standard. Even if it covered all changes and additions, we'd end up with redundant content because one or more features might have already been covered by their own topic.

With all this in mind, I would say that we should not make such topics (your votes should reflect this opinion for consistency), but I would gladly like to hear your thoughts.

1
  • Related to a similar question I posed in the Documentation Public Beta room which is what is the proper method for organizing content. I used the the Microsoft SQL Server dashboard and the tsql (poorly named) dashboard as a perfect example. When it comes to a language and language revisions, I wonder if the dashboard should target the language as a whole with sub topics to handle revisions as suggested in the Java 8 one that caught your attention? Commented Jul 25, 2016 at 14:36

5 Answers 5

14

I vote no

I think a topic should be for things like features or detailed information about namespaces/classes/objects etc. - there is already markup included in docs which allows for indicating that the example or topic is specific to a certain version of language.

The problem is that Documentation is categorised by the same tags in use on SO, but tags don't necessarily mean languages and so this isn't the correct way to organise the top-level items.

2
  • 1
    Additionally, the "versions" on the overview page could have a short list of new features in a new version of a tag
    – Justin
    Commented Jul 25, 2016 at 15:11
  • 1
    @Justin they normally have a link to the announcement of the new version or a changelog, which I believe most developers add a resume of the changes between versions.
    – Braiam
    Commented Jul 25, 2016 at 15:45
5

It's really up to the individual projects to announce new features; it's up to us to document new versions of languages as they become available. That's why Documentation has a version feature.

Now, once new major features warrant their own sections, we should definitely add them as appropriate. If a language that never had .. let's say ... reflection ... suddenly gets it, then that's probably a bowl full of stuff to document.

What we probably can do is give more visibility to tag wikis from Documentation, which is a great place to put more free-form stuff. That's actually a really good idea.

4
  • Actually, what the OP is asking is if we should have a section of "Features of C# 6" "7" and "8". BTW, C# 6 has it msdn.microsoft.com/en-us/magazine/dn802602.aspx
    – Braiam
    Commented Jul 25, 2016 at 18:20
  • @Braiam Well, that's on the MSDN Magazine site, not the documentation site... Commented Jul 25, 2016 at 18:22
  • @MikeMcCaughan is the first result of Google and is cannon, what else are you expecting?
    – Braiam
    Commented Jul 25, 2016 at 18:26
  • @Braiam I was expecting an argument for adding "Features of C# 6" to Documentation. A magazine, whose sole purpose is advertising Microsoft's developer-centered activity, is not documentation, and is hardly canon. Commented Jul 25, 2016 at 18:30
3

I typed "new features in Java 8" into DuckDuckGo and here's what I got:

enter image description here

Those are the official pages for new JDK 8 features and new Java language features. The latter has a couple of small examples and links to the official Java Tutorials, which have more examples of the features. (Though if you're a tl;dr, copy-paste programmer the Tutorials may be too helpful for your taste.)

There's simply no reason to duplicate that content in SO Docs.

If the content doesn't already exist on the Internet, there may be some value in having it in Docs. I think this would be handled better with a version filter in Docs (so users can find the topics/examples with different implementations in different versions), but if topics are the only kind of organization available in Docs, we have little choice but to abuse them this way.

1

Existing documentation in the wild (outside SO) does this.

It is highly desired, as existing developers want to update their knowledge. They know they don't need to (say) learn how lambdas worked in , but they also know they don't know the new features in . In fact, they might not know where the new features are!

Having a centralized list of what the new features are, and examples for them to teach someone how to use them, is highly valuable. Insofar as the SO Documentation system makes this bad (duplicates, long topics, discovery) it is a sign that SO Documentation system needs to be fixed, not evidence that this is a bad idea.

The version tags on existing topics are nearly useless for this. The topics are great if you don't know the feature, and want to learn it, and know what version of the language you are using. They are not useful if you know a version of the software, and want to be aware of the things you don't know yet.

To use documentation when you know version 7 of a software and want to learn 8, you basically have to read all the documentation, and note when it says >= 8. This is highly inefficient and a bad user experience.

Even a theoretical filter that picks out every >= 8 tag would be useless, as the same feature applied to many different examples would produce noise, you'd either be flooded with context or lacking it, and in general be another poor user experience. This is on top of the fact such a filter does not exist yet!

3
  • Why not just in the lamda topic have several examples with their if version? That was the main goal of the version thingy, that you can tell which versions the examples apply to.
    – Braiam
    Commented Aug 5, 2016 at 14:56
  • 1
    @Braiam Suppose I want to actually know what new features are in C++14. Even if I had some tool that only showed snippets marked >= C++14 it would still be useless, full of noise, repeated use of the same feature in different contexts, either flooded with exterior context or missing it, etc. And that feature doesn't exist. So, how exactly does your solution solve this problem? I mean, if you are "I have never used lambdas, how do I use them" the lambda topic is great. If I'm "I know C++11, I need to learn C++14" the embedded tags are nearly useless. Commented Aug 5, 2016 at 15:05
  • 1
    I've never found myself asking that question... in fact, for the let vs cons vs var in javascript I knew them for the "Statement > Declarations" topic in MDN developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/…, I'm not sure why you want a topic dedicated to just "new features".
    – Braiam
    Commented Aug 5, 2016 at 15:08
-1

I see nothing wrong with "(language-name) (major-version-number) features".

  • It's an important topic because it allows you to see the benefits of updating your compiler, to see a quick overview of features to explore them deeper later, to jump into using new features right away — all this without reading tons of documentation and filtering anything.

  • It's a popular topic, people actually search for this sort of information whenever a new version of a language is released or they update to the new version. Even between the versions, upcoming features of a language is a popular topic among enthusiasts.

  • These topics are already in the documentation. Overview of C# 3.0, The New and Improved C# 6.0 etc. If Microsoft doesn't see anything wrong with them, I don't see why we should.

Regarding duplication. Topics like this should include only a quick overview of new features. If a feature deserves a separate topic, then the overview should link to the full topic. Some duplication is unavoidable anyway, many tags and topics contain similar content right now.

While the topic suggestion for Java 8 was declined, C# Language contains topics for versions ranging from 3.0 to 7.0. 6.0 and 7.0 receive a lot of attention, so looks like people are interested in having them. ECMAScript 2015 may look empty right now, but give it some time, it was created only yesterday and edited by just one user.

I'd say topics like this perfectly fit Documentation, as they contain lots of useful examples which don't require any particular order.

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