Should we use ES6 in documentation?

[Reinmar]

The whole code is in ES6, so it's natural for us to use ES6 in documentation. We've done so in API docs so far and most likely will do so in guides, otherwise risking multiple personality disorder (like you have with two code styles).

The only problem is with samples which should run out of the box in all browsers that we plan to support... which includes IE11 :<. So, there are two options:

• Keep using ES6 everywhere for consistency and display an error if someone enter the docs with IE11 (that's 3% in case of http://docs.ckeditor.com). However, in the docs we'll also have samples where people should be able to check how the editor behave in IE11, so those samples must work. We could transpile the JS code which gets injected into samples, but leaving their source (also viewable on JSFiddle) as ES6.
• Use ES6 everywhere except in samples. Samples will be kept in samples/ directory so it's possible to create different linting rules for them, avoiding any mistakes. We're not going to write samples that often too, so this won't be that tiresome.

The 2nd option seems to be simpler and safer because the samples code will work everywhere. The only downside that it has is that in API docs and guides people will find ES6, when in samples they will not. OTOH, this is unavoidable because the whole code is ES6 anyway, so unless we keep everything ES6 way, there's always be inconsistency.

[Reinmar]

PS. One note - sample codes will be fairly simple, so there won't be much ES6 there. Some arrow functions and perhaps not more.

[scofalik]

I was going to say that I am for having ES6 everywhere and transpile samples code, but if you say that samples will be simple I am not sure.

If sample code will be easy to write without ES6 and it will look natural, we should be fine. Maybe people won't even notice that something is different.

Also, if developers want to use CKE5 in their apps but don't want to use transpilers, we should give them opportunity to see how the sample code looks like without using ES6.

I am for second option.

[pomek]

I have the same feeling like @scofalik.

The main question is - how many features from ES6 will we use? And second question - Are the features like "kill features" or more like "easier to development for us"?

Samples will be simple code, so we can do exception. I'm also for second proposition.

[pjasiun]

I think that we will support IE11 only for some time. Microsoft is doing it's best to move people to Windows 10 and Edge, so in, more-less, 2 years we may be able to drop IE11 support. I wonder what will happen with our sample then? Will we rewrite them to ES6?

[Reinmar]

Related ticket about browser support: https://github.com/ckeditor/ckeditor5/issues/236.

[Reinmar]

I realised that samples code will be accompanied by a lot of test code, so we cannot disable ES6 globally for samples/ directory (which would be yet another .jshintrc file with all the rules). It will be better to either disable ES6 for specific JS files or even for specific part of them.

[Reinmar]

I can see that we all used to ES6 and that all browsers supported by CKE5 support ES6 on such a level that we don't need to transpile our code at all that ES6 can be freely used in the docs.