search

WordPress / gutenberg

The Block Editor project for WordPress and beyond. Plugin is available from the official repository.
https://wordpress.org/gutenberg/
Other
10.51k stars 4.2k forks source link

A better onboarding experience for Block Development in the Block Editor Handbook #55432

Open juanmaguitar opened 1 year ago

juanmaguitar commented 1 year ago

The goal of this issue is to share a plan of action to provide a great onboarding experience for Block Development, taking into account the feedback received.

Discussion: Next Steps for Block Creation Documentation was opened 3 years ago and it has been a great resource for gathering feedback and coordinating actions to improve the Block Editor Handbook.

This feedback has been analyzed here and the following plan of action has been concluded as a good way to tackle most of the feedback received:

onboarding-handbook

The plan of action consists of 3 lines of action:

See detailed explanations of this plan of action ## 1. New version of`gutenberg-examples` The handbook docs need to be supported with real-life examples that can be executed and played with in local environments. The connection between the Handbook and the current https://github.com/WordPress/gutenberg-examples is a great idea but the implementation of this hub of examples referenced in the docs can be improved. This plan of action includes a new version of "gutenberg-examples" that addresses the feedback provided about it: - It uses ESNext and JSX by default - But it also contains "no-build" examples (ES5 and no JSX) as a reference - It provides developers with a clear list of examples nicely organized - It simplifies the creation of new examples - It provides an organization and convention that makes it very scalable - It allows developers to copy and paste each example into their own WP installations - It allows developers to see live examples (thanks to playground) - It allows developers to easily download each example - It allows developers to easily see in action (with `wp-env`) all the examples or any group of them - It provides a nice playground to experiment with blocks from existing examples This new version is available here: https://github.com/WordPress/block-development-examples - [X] It will be migrated to https://github.com/WordPress once all the current examples in https://github.com/WordPress/gutenberg-examples have been migrated. - [ ] Once the migration has been completed `gutenberg-examples-2023` will become `WordPress/gutenberg-examples` and the older version will be archived ## 2. Ideas and approaches to update There are a few ideas that have been detected and reported as pain points for block development adoption so the Handbook will be updated to alleviate them: - **`wp-env` as the only recommendation to set up a Local WordPress environment** - setting up a WordPress local environment can be a blocker for Block Development adoption as there are many options available so the Handbook will advocate for just `wp-env` as: - It is open-source - It helps minimize the tooling and configuration required to set up a Local WordPress environment - It's part of the WordPress.org project - **Only JSX and ES6 examples** - In the Handbook, there are currently two versions (see [How-to Guides / Blocks / Use styles and stylesheets](https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/applying-styles-with-stylesheets/)) which it may make sense a few years ago but it currently just add confusion to new developers, so the handbook will be updated to just use JSX and ES6 examples. - This will require, of course, a clear explanation of how the JSX and ES6 syntax require a build process to generate the final code that can be used. This will be tackled in the section "Getting Started > Fundamentals of Block Development > The Build Process" - The current examples in plain JS will be moved to examples in `gutenberg-examples` and a link to it can be provided just as a reference of how things can be done in plain JS - **Examples reviewed and updated** - All examples will be reviewed and updated and a related example in `gutenberg-examples` that can be tested will be referenced - **Static and Dynamic rendering vs Static and Dynamic blocks** - The duality of static vs dynamic blocks has been reported to be confusing as blocks are not exactly either static or dynamic. Speaking in terms of Static and Dynamic rendering is more accurate and less confusing as it would smoothly include blocks with `render.php` and `save.js` (which is considered by some core developers as a best practice) - the concept of Static and Dynamic blocks could be mentioned as a way to reference blocks with static or dynamic rendering ## 3. Revamped "Getting Started" section This work has already started in the issue https://github.com/WordPress/gutenberg/issues/54124 with the goal of restructuring the "Getting Started Guide" with the following organization: - Block Development environment - Node.js development environment - Get started with wp-env - Get started with wp-scripts - Get started with create-block - Quick start guide - Create a block tutorial - Fundamentals of block development - Anatomy of a block - Static and Dynamic rendering - Adding interactivity (To be added when Interactivity API is in core) - The Build process - The Block Data Lifecycle - Styling Blocks - Frequently asked questions - Glossary

Tasks

1. New version of gutenberg-examples

2. Ideas and approaches to update

3. Revamped Getting Started Section

Please share in the comments your thoughts about this plan of action to provide a great onboarding experience for Block Development.

Pinging @annezazu, @zzap, @gziolo, @jonathanbossenger, @ryanwelcher as they've been active participants of the conversation at https://github.com/WordPress/gutenberg/issues/22151

gziolo commented 1 year ago

Thank you for opening this issue as a follow-up for #22151. You captured nicely some of the talking points that weren't addressed in the previous discussion. I like how actionable this issue is in contrast to the previous one that fulfilled its purpose, and it became hard to contribute to over a longer time because of too many topics covered.

Requires "Fundamentals of Block Development > Static and Dynamic rendering"

We should further discuss how to best explain these ideas once the appropriate issue gets created. I'm leaning towards revisiting that aspect completely and using the nomenclature related to the block frontend rendering lifecycle where you have static HTML serialization in the editor (save), dynamic server processing and rendering (render), and in the near future client-side interactivity (view).

annezazu commented 1 year ago

Thank you for following up on this! I was always bummed the prior issue sat for so long and it's great to see new life being breathed into it.

jonathanbossenger commented 1 year ago

This is very exciting, and will also make it much easier to create educational content for Learn WordPress, following a similar path for the first-time block developer.

One question I do have is, what will be covered in the Styling Blocks chapter of the Fundamentals of block development section?

juanmaguitar commented 12 months ago

One question I do have is, what will be covered in the Styling Blocks chapter of the Fundamentals of block development section?

@jonathanbossenger I have opened an issue for that page sharing some key ideas to be covered in that page https://github.com/WordPress/gutenberg/issues/56275. The main takeaways for that page would be:

jonathanbossenger commented 11 months ago

Thank you for clarifying @juanmaguitar that is exactly what I would cover! 👍 In the handbook in the past block supports has always appeared after the custom stylesheets, when in fact supports is more useful to developers.