Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation: Consider removing all ES5 examples. #32430

Closed
youknowriad opened this issue Jun 3, 2021 · 7 comments
Closed

Documentation: Consider removing all ES5 examples. #32430

youknowriad opened this issue Jun 3, 2021 · 7 comments
Labels
Developer Experience Ideas about improving block and theme developer experience [Type] Developer Documentation Documentation for developers [Type] Discussion For issues that are high-level and not yet ready to implement.

Comments

@youknowriad
Copy link
Contributor

Maintaining ES5 and ESnext examples in the documentation is not an easy task, we've been doing that since the start of Gutenberg to allow folks to just use the examples without build steps, that said, now that we dropped IE11 support, the ESNext examples can work just as well (using globals instead of imports) in all browsers, so I think we should consider removing all the ES5 examples from our documentation to simplify it.

cc @gziolo @mkaz

@youknowriad youknowriad added [Type] Developer Documentation Documentation for developers [Type] Discussion For issues that are high-level and not yet ready to implement. labels Jun 3, 2021
@mkaz
Copy link
Member

mkaz commented Jun 3, 2021

🤔 People do use just ES5, not having the extra build step is a selling factor, just a couple days ago in #32360 we got a request for missing ES5 code. Even if globals work the JSX markup would need to be compiled.

The code examples section of contributing documentation does guide that ES5 examples are only needed for beginner tutorials, so I'm not sure there is an expectation to include for all code samples.

@youknowriad
Copy link
Contributor Author

I'm saying that now ESnext don't need a build step either so the only difference is the change in imports and I'm very open to using the globals directly instead of imports. It doesn't make sense to keep two versions of the code with just the imports/global being different.

@mkaz
Copy link
Member

mkaz commented Jun 3, 2021

Won't you still need a build for JSX examples? If one set works for both I'm all for simplifying 👍

@youknowriad
Copy link
Contributor Author

I guess you're right, that one slipped my mind 🤔

Our options could be to write hypersrcipt like syntax, or stick with JSX but accept that it doesn't work with no build system.
I do think keeping two versions of the code is confusing though.

@Netyson
Copy link

Netyson commented Aug 25, 2021

as a js beginner, i am very glad for the es5 snippes and documentation.
for smaller blocks i don't see why i should build a whole build environment when i can just write it like it is.

@kevin940726
Copy link
Member

ES6 is supported in all the browsers we support. Using ES6 doesn't mean that we have to use a build step though. Maybe making them into JSX and JavaScript makes more sense? We can automate this too to compile JSX into plain JavaScript when building the doc.

@gziolo gziolo added the Developer Experience Ideas about improving block and theme developer experience label Oct 16, 2021
@ryanwelcher
Copy link
Contributor

It seems that the handbook is using tabs for JSX and Plain now. I'm going to close this as per this discussion in Slack. Feel free to re-open if there are still outstanding items to discuss.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Developer Experience Ideas about improving block and theme developer experience [Type] Developer Documentation Documentation for developers [Type] Discussion For issues that are high-level and not yet ready to implement.
Projects
None yet
Development

No branches or pull requests

6 participants