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

[juanmaguitar]

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:

The plan of action consists of 3 lines of action:

• New version of gutenberg-examples
• Ideas and approaches to update
• Revamped "Getting Started" section

See detailed explanations of this plan of action

1. New version ofgutenberg-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

• 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) 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 #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

• Migrate examples from https://github.com/WordPress/gutenberg-examples to new version of "gutenberg-examples" → block-development-examples

2. Ideas and approaches to update

• wp-env as the only recommendation to set up a Local WordPress environment**
  • Done at Docs: Overhaul the Development Environment section of the Block Editor Handbook #54395
• Update examples to only JSX and ES6 version
  • Done at Remove all {% codetabs %} instances and any vanilla JS references. #56121
  • Requires and explanation of "The Build process" planned for Getting Started > Fundamentals of Block Development > Javascript in the Block Editor #56277
  • Related: Documentation: Consider removing all ES5 examples. #32430
• Review examples referenced from "gutenberg-examples" and ensure they match with the code displayed in the Handbook
• Review references to Static and Dynamic blocks and update them to speak in terms of Static and Dynamic rendering
  • Requires Getting Started > Fundamentals of Block Development > Static or Dynamic rendering of a block #56274

3. Revamped Getting Started Section

• Docs: Update the Getting Started section to provide a better developer experience #54124

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 #22151

[gziolo]

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]

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]

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]

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 #56275. The main takeaways for that page would be:

• Styles are usually centralized via theme.json so specific block styles should be flexible enough to allow different "skins"
• Blocks can define supports, custom style configurations for users via attributes and block styles among others to allow users to define the styles of the block
• Custom stylesheets and CSS properties for the block can also be attached to the block markup in the front to take control of the final design of the block.

[jonathanbossenger]

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.