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

Docs: Rename code example toggles to better represent current state #35776

Closed
mkaz opened this issue Oct 19, 2021 · 1 comment · Fixed by #37348
Closed

Docs: Rename code example toggles to better represent current state #35776

mkaz opened this issue Oct 19, 2021 · 1 comment · Fixed by #37348
Labels
Developer Experience Ideas about improving block and theme developer experience [Type] Developer Documentation Documentation for developers

Comments

@mkaz
Copy link
Member

mkaz commented Oct 19, 2021

The code examples in the developer documentation, as well as the gutenberg-examples repo, use a delineation between two types of code: ES5 and ESNext

With the dropping of support for IE11, the targeted browsers all support the ES6 syntax. So the distinction is no longer accurate, as it is not between ES5 and a newer syntax; but between not building JavaScript and using JSX that requires a build.

So I think we should rename the toggles and our usage within documentation to better reflect this distinction.

My suggestion is to name the toggles: "JSX" and "Plain"

We discussed this also in the core-js meeting today, and it was also discussed in this ticket.

Changing the toggles will also clarify whether we need two sets of examples, as there has been some discussion around dropping ES5 support in docs.

For reference, our documentation around code examples recommends including ES5 examples for beginner tutorials but not required for all code examples.

Also for reference, looking to see how other documentation manages, in the React tutorial they show one example using non-JSX and the rest of their documentation uses JSX. For Preact, in the getting started guide they show an example using a JSX alternate (HTM), but then the rest of the documentation uses JSX.

So an alternative, which I'm not necessarily for but I'll include for this discussion to acknowledge it as an option, is to remove the code tabs and add a new section explaining JSX and build.

What do y'all think?

@mkaz mkaz added [Type] Developer Documentation Documentation for developers developer-docs labels Oct 19, 2021
@gziolo gziolo added the Developer Experience Ideas about improving block and theme developer experience label Oct 20, 2021
@ndiego
Copy link
Member

ndiego commented Oct 21, 2021

I am biased, but I agree and recommend dropping all ES5 examples. I feel it is better to spend the effort educating new users on how to use JSX and more modern approaches to building with WordPress.

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
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants