doc: Revisit ES5 / ES6 / ecma next toggle for the API or having ES6 guide/topic

[eljefedelrodeodeljefe]

As per discussion on nodejs/node#6203 and PR nodejs/node#4915 we should have such a feature / content on the agenda again.

Churn might be actually welcomed...

[Knighton910]

+1

cc @nodejs/documentation

[stevemao]

I thought we already made a decision?

from @chrisdickinson

OK, the resolution on this from the meeting was:
We will look into changing the font / highlighting template strings differently to call them out.
We're going to look into ways to receive feedback from folks reading the docs, especially newcomers.
We'll continue to experiment with this approach in the future, but:
There are concerns about doubling the number of examples we're tracking & increasing the maintenance load for the future.

[eljefedelrodeodeljefe]

Can't remember, but somewhere somewhen we rather said to discuss it again. Not sure... if this dies off quick, I am good. However we should find a good solution for problems like in the linked issue.

[stevemao]

I think we should discuss "what's the better way of resolving it". Maybe we should fix nodejs/nodejs.org#434 ASAP (blaming myself)

[kahwee]

Once node v6 is released, we just have to deal with v5 and v6, both have ES6 enabled by default anyway. Wouldn't just displaying the docs in ES6 be sufficient?

[eljefedelrodeodeljefe]

It's a matter of style and teaching rather than what we support I fear. I guess core and a lot of people (including me) are prefering Class.prototype.method syntax over es6 class. Not only that, but also we would have lots of old SO questions and tutorials out there in es5. New users won't really see the change and might be mislead or plainly don't understand what is presented.

[jasnell]

slight correction, once v6 is out it will be v4 and v6, there shouldn't be any reason to keep v5 docs up.

[kahwee]

@eljefedelrodeodeljefe Are you intending this to be for v4 as well? Or just v6.

[eljefedelrodeodeljefe]

Well the idea would be to track ECMA not node versioning. Obviously going forward we would have to wait node / v8 to catch up to certain features before we can employ them in examples. But the gist would be: the community decides on a certain style for a major version of ECMAScript (es6: let, const, no classes; es7: class, async/await) and this then will be in there forever. Until, say, ES5 is so out of date that everyone wants to get rid of it.

If there should be any reason to track specific node versions then we should follow the LTS and HEAD tracks. As jasnell describes it v5 then would be obsolete, v4 would need to stay in.

If the tracking logic is unclear and/or there are other ideas we should discuss this further...

[kahwee]

Most beginner users probably don't care about ECMAScript 5, 6 or 7, they just want to know the recommended practice in nodejs v4 or v6 without using additional command-line options. Introducing too many concepts may confuse them instead of help them.

Even if we split things by ES5, ES6 and ES7, we still face varying amount of implementation of ES6 in the V8 engine as seen here.

As for whether we should use class or function, I think we can put it to a vote on that. Personally, I don't use class in my ES6 code either. I want to see terse functions using => but I don't expect ES6 to start throwing class as me just simply because it's part of the ES6 specification.

[stevemao]

I think this should be closed because of
nodejs/nodejs.org#671 (comment)

[eljefedelrodeodeljefe]

@stevemao they touch different topics. This here would touch every inline example in the API.

[stevemao]

I understand. But do you think this should be centralised on one page?
The reason why there is a centralised page talking about es next is because we don't want to mention it repeatedly in different examples.
Even though API and the rest of the website are two different projects, the idea is similar so we should point people to the same page (node.green)?

[chrisdickinson]

If we're moving examples universally to ES6, that is probably OK. With regards to a split ES5/ES6 example solution, I think the prior resolution holds — that's too much work to maintain, roughly doubling the number of examples.