Discussion: Next Steps for Block Creation Documentation

[annezazu]

Context

The Block Directory was first announced just over a year ago and has the eventual aim of enabling users to install single block plugins directly from Gutenberg while editing! This direct installing feature will be a huge step in the right direction for unlocking the power of the Gutenberg editor. Need a block to set up payments? Install and set it up without leaving the editor. Right now though, the process of creating blocks for developers is confusing and has some accidental gaps.

This is where this issue comes in and where your help is needed! What gaps do you see in the current documentation? What do you think about the following overall headers and tasks? Let’s make it easier for developers to create blocks for users to play with in the future by gathering next steps for block creation documentation and diving in.

Consolidate Instructions and Crosslink

The ultimate goal here is a canonical information source for block developers who wish to contribute blocks to the directory. To accomplish this, there needs to be both the creation of and clear differentiation between official documentation vs tutorials as @zzap notes.

• Create new sections in the handbook for a “Creating Blocks” tutorial and "About Blocks" as official documentation. Right now, we just direct folks to the tutorial without further context and there needs to be separate sections depending on the audience. Docs: Create a Block tutorial #22831
  • https://developer.wordpress.org/block-editor/getting-started/create-block/
• Repurpose the Block Tutorial and Gutenberg workshop materials from @mkaz as the basis for the “Creating Blocks” tutorial. Docs: Create a Block tutorial #22831
  • https://developer.wordpress.org/block-editor/getting-started/create-block/
• Make the link to the new “Creating Blocks” section more prominent within Gutenberg’s readme. This could include having similar bullet points like the “Using Gutenberg” section has. Docs: Add links for Create a Block Tutorial #23946
• Add a notice on the main Block Editor Handbook page linking to the new “Creating Blocks” tutorial to immediately help folks know where to go to get started. Docs: Add links for Create a Block Tutorial #23946
• Define more clearly what’s allowed for blocks (prior discussion) and include the outcome in the "Creating block" tutorial. Documentation: Add block submission guidelines. #23545
• Document the process for getting a single block plugin uploaded to the block directory as part of the creating a block tutorial. Documentation: Add block submission guidelines. #23545
• Reference Single Block plugins in the Introduction to Plugin Development handbook.
• Restructure the block registration docs in the developer handbook to be easier to follow Consider restructuring Block Registration docs in handbook #20161
• Consolidate information about blocks and the block directory to make up official documentation separate from the tutorial.

Overall, this area of improvements touches on this proposal as well: #18680

Make the First Step Magical

Great developer documentation often has a magical first step that enables someone to have a quick win early in the exploration process. Right now, this quick win is hidden from those trying to create new blocks.

• Incorporate @wordpress/create-block more clearly into the block tutorial. Docs: Create a Block tutorial #22831

• Remove WP-CLI references from the block tutorial. Docs: Add links for Create a Block Tutorial #23946

• Clarify block.json (and perhaps autogenerate it Create Block: Generate a block.json file #23399

• Break apart the gutenberg-examples repo into different repos to provide a “clone and go” option for new block developers. When doing this, make sure to recreate using @wordpress/create-block for consistency and to list examples focusing on ESNext versions as the default.

• Add links to React docs where it’s considered that React docs should be consulted. This will likely take the form of a technical audit.

• Clarify that for block registration, the parent can be empty: Documentation: Clarify the behavior of parent when empty during block registration #15731

Since we require this file for block registration, this proves to be a hurdle for folks to cross in creation of new blocks that can appear in the block directory. As a result, we should focus specifically on improving the official documentation around this particular file.

• Create varied examples of proper block.json.
• Incorporate ESLint rule work to make writing block.json less error prone.
• Explain the “why” behind needing this file in the documentation and what purpose it’ll serve in the overall block directory.
• Reference register_block_type_from_metadata function which is used to register blocks using block.json. Note: there is some work remaining on this function, namely that it does not handle i18n and right now is only in the Gutenberg plugin.
• Make sure all examples in gutenberg-examples repo include a block.json if required.

Please share in the comments anything that’s missing. Teamwork makes the dream work and this is meant to be a jumping off point for dialogue and task assignment.

Big thanks to @mkaz for working on this with me 💥

[zzap]

Thank you @annezazu for this detailed plan. It gives hope to Documentation team.

As I am not familiar with plans for best practices and requirements, I'm not going to comment on that. I will comment on actual problems I found in creating blocks tutorials.

Make the First Step Magical

This is essential. Being able to follow tutorial and get expected result is what makes people stay, and failing to do so, leave. In this regard I have to mention tutorials made by Gatsby.js, which I was able to follow through and get exact result without ever writing a line of React before.

I believe that here we have to take in consideration the audience for these tutorials. This should be the first place where PHP developer comes to get the information on how to build the very first block. We cannot expect any prior knowledge in React. The knowledge that we can expect is the kind of knowledge developer can get in DevHub. This is PHP and a little bit of terminal. And it's not just syntax. It's the whole philosophy and the way React works that we haven't seen before in WordPress.

I'm not saying we should go in detail about React's philosophy here. I'm saying we should start from the known place and guide through unknown by clearly defined steps. We have to be sure what is the purpose of each step, what knowledge is to be gained from it and where will it lead next.

So, following the creation of block tutorial, I'm going to fail at the first example. It says:

// automatically load dependencies and version
$asset_file = include( plugin_dir_path( __FILE__ ) . 'build/index.asset.php');

It doesn't say where I get this file from and since when I have build folder. It just says that this "shows using the wp-scripts build step that automatically sets dependencies and versions the file". When I follow this link, if I do it, I find explanation at the very bottom of the page, in Dependency Management section. Reading through the whole page, I forgotten what I was looking for.

In explanation of the script dependencies, I'm really missing the information that everything I import in my .js files, I have to include here as an dependency. It's logical when we think about it but between the time I'm enqueueing the script and importing something from other than wp.blocks and wp.element, I'm gonna forget that I have ever seen this. Also, I think this info should be included every time new package is introduced.

Moving to registering the block I get the example (default ESNext) for registering the block but it doesn't say where should I put this code. I enqueued build/block.js so I guess I should create build folder and block.js file in it. But if I paste this code into that file, it won't work because it needs Babel to process the code, and Babel needs Webpack, and all that is conveniently packed in @wordpress/scrips, but we don't know that yet.

And even if I got everything right and used @wordpress/scrips, I will get an error for this line:

import { registerBlockType } from '@wordpress/blocks';

Error:

Module not found: Error: Can't resolve '@wordpress/blocks'

So before going to register anything, even though that is the goal, we need to get familiar with the development environment, we need to see the file tree for one block, to understand where things go and how it's gonna build the build. We need to see that package.json and webpack.config.js files and to understand their part in developing block.

We need to use @wordpress/create-block package from the beginning, rather than download the plugin with completed examples, as suggested on the introduction page. Whichever is planned to be the standard, we need to use it in our examples consistently.

This is just the first page of tutorial on building block. For someone who has never wrote any React code, it is impossible to move on from here. They will give up on learning and, when knowing becomes requirement, they will download that plugin and try to force in the functionality they need. They will never move forward.

Another symptomatic issue in block editor's documentation is the kind of links to other pages that appear. These links are promising to further explain the piece of information but not only do they fail in explaining it in a way that I can continue with the tutorial, they actually require more knowledge in order to understand the explanation. And quite often, they link to other pages in a similar manner.

If this is the right place, I can continue analysing tutorial pages and report my findings here. If not, then this comment can be used as an example of missing informations.

[oandregal]

I believe that here we have to take in consideration the audience for these tutorials. This should be the first place where PHP developer comes to get the information on how to build the very first block. We cannot expect any prior knowledge in React. The knowledge that we can expect is the kind of knowledge developer can get in DevHub. This is PHP and a little bit of terminal. And it's not just syntax. It's the whole philosophy and the way React works that we haven't seen before in WordPress.

I think this is a great conversation to have. My view is that docs should aim to onboard a wider generation of people: people that know the world of WordPress PHP as well as people that know nothing about WordPress.

In this view, what follows is that the minimum requirement would be that you can navigate/understand code in basic PHP & JavaScript (or be willing to learn as you go), as well as be comfortable enough with the terminal to be able to work on things. What's a blocker depends on a person's background: for some, it can be the WordPress hooks system, for others the JSX syntax in JavaScript code, so it's always recommended to point to external resources for those. We should be mindful of not assuming that people already know the way of WordPress PHP. In working in Gutenberg, I see a lot of new contributors that have no prior experience with WordPress.

[fabiankaegy]

@annezazu Regarding breaking the Gutenberg Examples up and creating an easy way for them to be used within create-block. With the input of @gziolo I started on a Implementation that would allow anyone to pass the name of a npm package to the create-block cli as the --template. And if the package exists it would go ahead and use it as the template.

I have a working demo of it and will create a PR with what I have build shortly.

As for converting the examples over and adding documentation for the process I know, that @brezocordero, @anjadeubzer, @rbest, @jessynd, @amberchunn and @intelijens are working on something there so we can tie what I build and their efforts together :)

[gziolo]

@mkaz, you should follow #22175 where @fabiankaegy is quite close to make it possible to wire external templates (npm packages for start) to Create Block. It would make it very straightforward to convert Gutenberg Examples into one line call that generates every plugin in the state ready for activation in every WP instance.

[aaronjorbin]

With the thought of recreating the examples, I think it's going to be important for those to include tests ( see #21360 ).

My view is that docs should aim to onboard a wider generation of people: people that know the world of WordPress PHP as well as people that know nothing about WordPress.

100%. I think it might be valuable to research and come up with the personas we want the documentation to be aimed at before getting too far into planning what is in it. Some examples of the folks I work with who I expect to be writing blocks in the coming months:

• An experienced WordPress Developer who is new to Blocks. They have experience with modern JavaScript (including React), deep knowledge of WordPress core methodology, and have used Gutenberg extensively, but have never written a block themselves.

• A junior developer that only has ever written modern Javascript and who has been exposed to WordPress, PHP, and JavaScript, but is far from familiar with WordPress methodology or coding and is more comfortable in JavaScript than PHP.

• An experienced PHP WordPress developer. They are comfortable writing JavaScript, but are much more familiar and comfortable writing PHP.

• A midlevel JavaScript/TypeScript developer with extensive experience in React, but only passing knowledge and familiarity with WordPress and PHP.

[annezazu]

@zzap Thank you for diving right in and offering up such stellar insights into what the current process is like. I love it and appreciate you taking the time.

If this is the right place, I can continue analysing tutorial pages and report my findings here. If not, then this comment can be used as an example of missing informations.

Reading over your comment, it struck me that you might be the perfect person to take on this task if you're at all interested: "Add links to React docs where it’s considered that React docs should be consulted. This will likely take the form of a technical audit." Further, after work is done to both rearrange and update documentation to be more for a targeted audience of developers new to React, you'd be a perfect person to give feedback. Right now though, this above proposal seeks to create new docs based on much of what you're talking about (like using @wordpress/create-block package from the beginning) and is focused on gathering momentum to do so. After work is done to create a new version though with this in mind, there will still be a need for someone to review and critique the next versions. What do you think? I am open to approaches here and definitely want to use your feedback and approach in the most apt places.

We should be mindful of not assuming that people already know the way of WordPress PHP. In working in Gutenberg, I see a lot of new contributors that have no prior experience with WordPress.

@nosolosw this is a fantastic and related call out. Gutenberg has undoubtedly brought in new people into this project and work should be done to embrace that rather than assuming baseline knowledge. This too is where docs should link out to relative spaces even if it's back to WordPress PHP docs.

@fabiankaegy absolutely lovely and exciting news! Thank you for connecting dots here and for your efforts to make aspects of this work even easier <3

[zzap]

I've been in documentation team for a long time and I have proposed this particular part of block editor documentation (tutorials on extending) as a project for Google's Season of Docs. We proposed 9 projects and if this one gets selected, in September I'll be working closely with professional technical writer to make these tutorials the best possible.

So the answer to your question @annezazu is that I'm all for it. I've been writing docs for a long time and, as a developer, I've been using docs for a long time. There is no reason for these tutorials to be anything less than useful but I believe we can make them great. I'll be here, following the process all the way and happy to help in whichever phase of it I'm needed. Looking forward to it.

I agree with @aaronjorbin and @nosolosw that we need to know who we are talking to. We also need to make the difference between official documentation and tutorial.

Official documentation is documenting the software, how it works, its properties, what to expect and why. It doesn't care about your previous knowledge, it's not responsible for it. It is responsible only to document the facts about own topic.

Tutorial aims to teach and it expects your lack of knowledge on the subject. It explains the building and thinking processes, it measures the portion of given information and guide collecting information in a logical and structural way. It is concerned about your previous knowledge and its only purpose is to expand it so it can be used efficiently in every day work.

@fabiankaegy is there any place where this docummenting is happening? I'd love to take a peek :)

[annezazu]

Thanks so much @zzap - super excited all around to have you helping here and am glad to hear this was included already in the Season of Docs work 💥Your insight around tutorial vs official documentation is so on point. I'll edit the above as best as I can in light of what you shared so we're all on the same page.

[mkaz]

As far documentation level, it's hard to discuss in the abstract. In general, I feel we should be aiming lower towards junior developers because more experienced developers can skim what they are comfortable with. The documentation shouldn't be aimed at teaching some one programming, but how to get started and developing on WordPress and the Block Editor.

I think for any tutorials, if we can state up front stating any assumptions; For example, "This tutorial assumes a basic knowledge of JavaScript". I'm not sure if we should link to external sources on how to learn JavaScript, any good free open source ones?

I think for reference documentation, we can assume the users have gone through the tutorials. If anything in particular is complex, link to a related tutorial that explains it.

@zzap Instead of "official documentation" I prefer to call that "reference documentation" so something like API reference, it is simply documenting what the API does. I agree no extra walk-through required, but good examples of it in use is great!

[mkaz]

I have an outline for the Creating a Block tutorial, I created a similar I published on my blog that I walk through starting with dev environment to a complete block. I can work on converting over, though I think I'd switch the example block to something else, also I'll drop the screencasts part since that took quite awhile.

https://mkaz.blog/tag/build-a-block-series/

Basic outline, we could enhance and add sections as we go:

    Part 1: Development Environment
    Part 2: WordPress Plugin
    Part 3: Anatomy of a Block
    Part 4: Block Attributes & Data
    Part 5: ES6+ Syntax
    Part 6: Block Code
    Part 7: Placeholder Experience
    Part 8: Finishing Touches (Help/Examples)

[zzap]

This is wonderful. Thank you @mkaz

I'd love if we could create examples for (almost) every component, not just <TextControl />. If this is too optimistic then at least to cover elements people use often or complex ones etc. We could group them by some shared criteria.

Let me know how can I help.

[rbest]

Agreed. I have done this block series by Marcus. I built along side him the QRCode. The whole series was very helpful. We could use this as an onboarding support documentation. There is a few areas we need to update and maybe a few screen captures alongside concise steps and I think this could be dynamite! Rita Best Sent from my iPhone

…

On May 18, 2020, at 2:11 PM, Marcus Kazmierczak ***@***.***> wrote:  I have an outline for the Creating a Block tutorial, I created a similar I published on my blog that I walk through starting with dev environment to a complete block. I can work on converting over, though I think I'd switch the example block to something else, also I'll drop the screencasts part since that took quite awhile. https://mkaz.blog/tag/build-a-block-series/ Basic outline, we could enhance and add sections as we go: Part 1: Development Environment Part 2: WordPress Plugin Part 3: Anatomy of a Block Part 4: Block Attributes Part 5: ES6+ Syntax Part 6: Block Code Part 7: Placeholder — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

[gziolo]

I quickly skimmed your tutorials and videos included. Some questions and thoughts that I had:

Part 1: Development Environment

1. Can it use wp-env now or do you prefer Local by Flywheel for some particular reason?
2. Using VSC is a great idea :)

Part 2: WordPress Plugin

1. I guess it's where npm init @wordpress/block qrcode-block -t tutorial-step-1 (template to be created) could be presented to scaffold the most basic block possible using all the defaults provided. The code walkthrough happens afterward but people could skip if they don't care yet.

Part 3: Anatomy of a Block

1. This section could start with npm init @wordpress/block -t tutorial-step-1 where the interactive mode trigger allowing to provide block metadata from CLI.

Part 4: Block Attributes & Data

It could be split into two parts, maybe:

1. Importing code from WordPress packages that should cover npm start (npm run build) and how they handle script handles with asset files (@wordpress/blocks and @wordpress/components) behind the scene, I guess TextControl should display something without wiring it with attributes. Scaffolding happens with: npm init @wordpress/block qrcode-block -t tutorial-step-2.
2. This part would cover how to define attributes and combine them with the imported component. Scaffolding happens with: npm init @wordpress/block qrcode-block -t tutorial-step-3.

Part 5: ES6+ Syntax

1. Should it be swapped with Part 4 or do we keep it as npm init @wordpress/block qrcode-block -t tutorial-step-4? Maybe there should be less ES6+ in the code before :)

Part 6: Block Code

This is where it gets complex because of the code rendered on the front-end. npm init @wordpress/block qrcode-block -t tutorial-step-5?

Part 7: Placeholder Experience

npm init @wordpress/block qrcode-block -t tutorial-step-6?

There could be one more step where RichText is used to add a description for the QRCode, but mostly to raise awareness that is the most important piece of the experience :)

[gziolo]

@mkaz, as usual, I took for granted that tutorials exist on your blog and I immediately focused on the feedback 🙃

Let me emphasize now your awesome work on putting it all together with videos (plus all instructions left as the content of posts). Major props for all the great work ❤️

[mkaz]

@gziolo No worries, and I appreciate all the feedback. I would update and adjust it all to fit with all the new tools when making it part of the official docs. 👍

I'll take it the general outline is a good starting point and can start putting together a PR to bring it over.

[jonathanbossenger]

Having recently worked through my own process of learning to build blocks for an existing plugin, I'd like to share my thoughts on things to consider when updating the documentation. Mostly these are areas where I bugged @gziolo (thank you) during my journey, as I could not find official answers elsewhere.

Dive deeper into the tooling required (nodejs, npm, wp-scripts), many WordPress developers are completely new to any sort of package management and the processes of managing these packages. If you're coming from PHP and are used to composer, you already have some idea, but many folks don't have that experience.

Include some background to writing code in a non-procedural way. Many WordPress theme developers are used to the process of using action and filter hooks and callback functions, and the switch to a more modern JavaScript approach can be confusing.

One of the biggest hurdles I faced early on was getting used to the JavaScript shorthand.
Something as simple as this, if you've never seen arrow functions before, could be difficult to comprehend.

save: ( ) => {
         return (
             <div> Hello in Save.</div>
         );
     }

I know the block tutorials are not supposed to teach folks JavaScript, but for many folks WordPress taught them PHP, and now that they think in PHP structures, and the closest they come to JavaScript is jQuery. Making this mental switch to pure JavaScript might be difficult. While the current ESNext/ES5 toggle is handy, it might be useful to include a short section in this.

Most of the tutorials/examples in the wild are plugin specific. Great if you are a plugin developer, but not so much if you're a theme developer who wants to add blocks. So it might be useful to include documentation on how to set up for a plugin as well as theme.

Clarify how to load plugin assets. I found that in one part of the tutorial, enqueue_block_assets and enqueue_block_editor_assets was used to load the main block JS, whereas in another part register_block_type was used. This creates confusion with someone new to developing blocks as to which one to use. Ironically both options can be useful for different use cases, so perhaps detailing what both do, but which is preferred, would be more useful

This one was more specific to my situation, but I found it confusing as to whether I should import block dependancies using this syntax
import { registerBlockType } from '@wordpress/blocks';
vs this syntax
const { registerBlockType } = wp.blocks;
This was because some example code I was looking at from a course elsewhere uses the latter. So it could be useful to cover the differences, and again, which is the recommended way.

I'm not sure about this one, as again, this was very specific to me and my requirements, but a section on building a custom component for a block (ie not based on an existing WordPress block components) may also be handy, perhaps as an advanced topic.

Thanks to @annezazu for bringing this to my attention. Also to @mkaz I wish I had found your tutorials when I was learning to build blocks. :-)

[jonathanbossenger]

One final thought, while I agree that the Block Editor documentation should not be aimed at teaching some one programming, there is a big difference in syntax between what many folks are still doing in PHP, and what is possible with modern JavaScript. So I do think it would be useful to keep this in mind when updating the documentation.

[zzap]

This one was more specific to my situation, but I found it confusing as to whether I should import block dependancies using this syntax
import { registerBlockType } from '@wordpress/blocks';
vs this syntax
const { registerBlockType } = wp.blocks;

I wouldn't say that it's specific to your situation. I've found them confusing as well. Especially because of inconsistent usage in examples. Without explanation what's the difference, it's easy to assume there's no difference at all. Yet another way to do things. Until you get an error with one and success with another.

Most of the tutorials/examples in the wild are plugin specific. Great if you are a plugin developer, but not so much if you're a theme developer who wants to add blocks. So it might be useful to include documentation on how to set up for a plugin as well as theme.

As a developer I 100% support this one.

However, themes at WordPress.org are not allowed to create blocks. Blocks can be created only in plugins for wp.org repo. For this same reason Theme Developer Handbook doesn't cover custom fields, meta boxes and all the other ways of getting content from user. Because this content is lost when theme is changed. It is not lost if it's gathered via plugin.

So, as a documentation team member, I have to disagree with including this in documentation and tutorials on wp.org. Again however, we recently decided to allow external links from trusted resources and soon this will take effect for complete wp.org documentation. If some of those trusted websites appear to have a good and valuable tutorial on building with block editor in themes, we'll be happy to add it to appropriate place.

[jonathanbossenger]

However, themes at WordPress.org are not allowed to create blocks.

Ah, I was not aware of this, not being a theme developer :-) But thanks for clarifying, in that case I retract my suggestion around adding documentation support for themes.

But that does raise an additional question, in that we perhaps do a little more in helping theme developers build plugins, or make a note that currently block registration needs to be done in plugins, as they might not be aware of how that all works? One of my first WordCamp talks was an intro to plugin development, and it was fully attended, and mostly by theme developers.

So if needing to learn how to build a plugin is another hurdle to building blocks, we may need to better remove that hurdle also.

[zzap]

I agree on clarifying what is for theme and what for a plugin. Theme is free to use all the available hooks and, obviously, add_theme_support features. But it's not specified in docs.

As for helping theme developers to learn how to build plugins, I'd say that's just one scenario. We have Plugin Developer Handbook for everyone who wants to build plugins and Theme Developer Handbook for everyone who wants to build themes.

So, it would seem like they only need to want and just go to Handbook but it's not that simple, isn't it? I believe we are missing tutorials on all levels at wp.org. The same way we are planning here tutorials for developing with and on top of block editor, I think we should have tutorials on developing themes and tutorials on developing plugins. Current Handbooks are somewhere in between documentation and tutorial and many things are left unsaid and unexplained. But that is a whole another story, off topic for this discussion.

[jonathanbossenger]

It does raise a good point though, I was thinking that the way the current block editor handbook seems to be a mix of core developer documentation, plugin developer documentation, and tutorial, could be confusing for newcomers. So I think part of this process should also take that into account and maybe separate the different sections.

[gziolo]

@jonathanbossenger great feedback, thanks for sharing. You covered the most pressing issues that are on the radar.

Personally, I struggle the most when I see how much PHP code is still necessary to register a block. Fortunately, there is quite good progress on #22519 where I propose some additions to the new register_block_type_from_metadata helper that should land in WordPress 5.5 and make the process of registration as simple as:

function create_block_esnext_example_block_init() {
	register_block_type_from_metadata( __DIR__ );
}
add_action( 'init', 'create_block_esnext_example_block_init' );

assuming that you use @wordpress/scripts and have block.json file that contains paths to the scripts and styles:

{
    "name": "my-block",
    "editorScriptPath": "build/index.js",
    "editorStylePath": "build/index.css",
    "stylePath": "build/style.css"
}

Having that, the recommended way will become to use ES Modules:

import { registerBlockType } from '@wordpress/blocks';

because wp-scripts start is optimized to work with import statements.

To respond to your example of using arrow functions, it's perfectly fine to use:

save: function( ) {
    return (
        <div> Hello in Save.</div>
    );
}

The only reason why you will see arrow functions more often is the fact that it's shorter 🤷

[jonathanbossenger]

@gziolo thanks for the feedback. I do think that the new register_block_type_from_metadata is great, however as one of those old PHP developers :-) having a PHP way of doing things is also valuable, and helps with the transition.

My main goal with raising some of these 'multiple ways to do the same thing' is to ensure that we
a) make sure the official docs show the new reader our preferred method but also
b) explain any legacy ways to do something
The mean reason behind this being that due to the rapid nature of the block editor's development, there are, and probably still will be, code samples, tutorials and courses out there, doing things the old way.

I may be wrong, but one of the struggles a fast moving project like this one has, is keeping it's documents up to date with the newest developments.

The only reason why you will see arrow functions more often is the fact that it's shorter

Oh, I agree wholeheartedly, I was just pointing out that for folks new to the shorthand, it can be very confusing. When you're used to seeing the word function in front of ALL your functions and class methods for the last 17 years, suddenly not seeing it is definitely a jarring experience :-)

[jonathanbossenger]

@annezazu forgive me if this is the case, but is this issue linked from a make blog post somewhere. If not, it might be useful to get feedback from folks not actively monitoring this repository?

[annezazu]

@jonathanbossenger there is not an individual post specifically for this overall issue but it has been referenced in meeting notes as something people are working on (example) and discussed/shared in various slack channels (core-editor, core-js, docs). Do you think this warrants an individual post? I'm happy to write one but it feels a bit like overkill at the moment. It seems like right now it would be helpful to do a push for feedback after a certain level of improvements.

[jonathanbossenger]

👍 Nope, I think a meeting note reference is perfect.

[skorasaurus]

related: #8733

[kristinabressler]

Hi. While I do have experience working in WP and creating WP themes. I am new to learning about blocks. Therefore, someone gave a link to learn about blocks: https://developer.wordpress.org/block-editor/tutorials/block-tutorial/. However, I thought I should start with the prerequisites in which I can set up development environment and a new wordpress site, which is at: https://developer.wordpress.org/block-editor/tutorials/devenv/. However, I got stuck after the step "install npm -g install @wordpress/env" It said after this: "Start the environment from an existing plugin or theme directory, or a new working directory:" I thought I was missing something so I tried to look around online if someone followed the Block tutorial and wrote what they did. I also came across https://davidyeiser.com/tutorials/docker-wordpress-theme-setup that should help me set up a new environment and new Wordpress site with Docker.

Is this the correct way I should be going before I download the "https://github.com/WordPress/gutenberg-examples" to work with as I go through the tutorial?

[gziolo]

@annezazu – where are we with this issue? It's hard to tell after over a year of constant refinements applied to the block editor handbook 😄

We have three pieces that work quite nicely:

• Create a Block Tutorial – https://developer.wordpress.org/block-editor/handbook/tutorials/create-block/
• Block API Reference Guides – https://developer.wordpress.org/block-editor/reference-guides/block-api/
• Block related filters – https://developer.wordpress.org/block-editor/reference-guides/filters/block-filters/

There is also a section on How-to Guides about blocks that seems to be very outdated:
https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/

In some ways, it also duplicates the content covered in Create a Block Tutorial and Block API References Guides. It would be important to update this section, maybe remove redundant outdated content and link with other materials.

I'm currently working on the dev note for Block API changes coming to WordPress 5.8 that will also contain recommendations to use block.json and register_block_type as the preferred way to register block types in WordPress. The draft of the note can be found at: https://gist.github.com/gziolo/cbea77500316a243e445d509ced3c231. Once it's published, I'm going to move the missing parts to the handbook.

[annezazu]

This issue is in a place of needing an update :D I know @DaisyOlsen has been digging into documentation as well and it's my hope to have more time in the future, depending on the FSE Outreach Program.

Once it's published, I'm going to move the missing parts to the handbook.

That sounds fantastic. Thank you for following up here and nudging. It's on my list to loop back on but I welcome others to jump in here too.

[ryanwelcher]

@annezazu @gziolo I am planning on digging into the existing documentation over the next couple of weeks to get a real sense of where they stand in the sense of the changes with 5.8 that @gziolo called out above.

In the meantime, here's my $0.02 😄

Moving everything towards using the block.json drastically changes the approach to registering custom blocks and abstracts some items away ( i.e enqueuing editorScripts and other assets ) which, while making the registration process simpler, requires explanation and explicit details on what is happening behind the scenes and the reliance on a build process.

This is less of a concern with developers with no block experience pre 5.8, but for those who do, it can be confusing which function to use register_block_type, register_block_type_from_metadata or the "new" register_block_type and why when looking at an older codebase, the two register_block_type calls have different params - this is explained very well in your post @gziolo but I think the examples in the handbook also need to call it out. This does make me wonder if we need a section on upgrading blocks?

This is a much larger discussion ( perhaps in another issue? ) but I 100% agree with @aaronjorbin's point above about trying to define the audiences. While I don't think we can account for every combination of technical experience or teach programming in general, we should be aware that some of the audience may know nothing about WP/JavaScript/React/CSS/{Insert tech here} and not assume any base knowledge, or if we do be explicit on what with links to external learning resources.

Based on this thread, I think we can look at these items now but would love any feedback/comments/concerns:

• Audit and update the items here - https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/
• Create a new tutorial/section that pertains to converting an old plugin to use Gutenberg. The example @mrleemon added above is a great use-case.

[annezazu]

Absolutely love what you're thinking, @ryanwelcher. This sounds excellent and I appreciate you stepping in to drive this work forward 🤗.

[mkaz]

@ryanwelcher Great for digging in and looking forward working with you to help the docs. To explain the current structure of docs in place, it's mostly due to organic growth and the slow migration to a more organized setup. A big effort went in earlier to get the initial higher levels of documentation into the four types of docs as explained here.

I have a PR ready here (#34091) to move a few more pieces around, but that should give us the basic structure in place.

However, we haven't quite gone through and cleaned up the existing content and docs themselves to match. So for example the how-to-guides/block-tutorial which was the very first tutorial but now should be shaped into smaller individual topics, like stylesheets or InnerBlocks.

Also, we could use some help organizing, for example looking at the content in How to Guides and see what should be in Tutorials

Feel free to ping me any time and I can help.

[ryanwelcher]

Thanks @mkaz! I'll review the linked resource and get myself up to speed with the current efforts and direction. Looking forward to working with you as well!

[gziolo]

From #22151 (comment):

There is also a section on How-to Guides about blocks that seems to be very outdated:
https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/

In some ways, it also duplicates the content covered in Create a Block Tutorial and Block API References Guides. It would be important to update this section, maybe remove redundant outdated content and link with other materials.

From #22151 (comment):

However, we haven't quite gone through and cleaned up the existing content and docs themselves to match. So for example the how-to-guides/block-tutorial which was the very first tutorial but now should be shaped into smaller individual topics, like stylesheets or InnerBlocks.

It feels like we should start with the old block creation tutorial and repurpose it more towards recipes of how to approach different aspects of building blocks. Many of the code were copied from https://github.com/WordPress/gutenberg-examples, so we should also decide whether it's time to archive this repository or move to another place to make it easier to keep it up to date.

The other task we discuss in #25188 is adding a tutorial for creating a plugin with multiple blocks. It would be great to have it all integrated with @wordpress/scripts and @wordpress/create-block to make the process more automated.

[ryanwelcher]

Many of the code were copied from https://github.com/WordPress/gutenberg-examples, so we should also decide whether it's time to archive this repository or move to another place to make it easier to keep it up to date.

Just a followup that all of the examples at https://github.com/WordPress/gutenberg-examples have been updated to reflect the most recent APIs'

[juanmaguitar]

In favor of using only JSX/ESNext version of code examples vs using both JSX & Plain

Hi! 👋 I see in the Contributor Guide of the Block Editor HandBook there's a section about Code Examples that recommends using JSX and Plain versions of code examples.

I know there are different perspectives and opinions about this but I would like to share my opinion and maybe reopen this debate just to make sure the reasons why we have this still remain strong.

I think only displaying the more modern version of the code (JSX , ESNEXT ...) in the code examples (with proper explanations to include others stacks) should be enough. IMO documentation should be opinionated to guide the user and simplify the number of decisions they have to take when using the information read in the docs.

The recommendation to create a block is to use the @wordpress/create-block that includes the tools to build the block and transpile the code from ESNext to ES5 with easy scripts and ver good documentation about it. Isn't this enough to display only the code that works with this setup?.

Being aware that there are a lot of developers that are not comfortable with JS setup tools and that they prefer working w/ ES5 directly and no build process. Has this been measured somehow? I mean, is this a majority of people? Compared to what? How do the ones that prefer ES5 code develop blocks?.

From my point of view, I think this may be one of the reasons (one of many) Block Development is still not very attractive for Javascript developers. Has this been considered as a factor to be taken into account? I think having a "modern" version of the code would be both didactical and attractive for new learners and experienced javascript developers.

[gziolo]

In favor of using only JSX/ESNext version of code examples vs using both JSX & Plain

Hi! 👋 I see in the Contributor Guide of the Block Editor HandBook there's a section about Code Examples that recommends using JSX and Plain versions of code examples.

I know there are different perspectives and opinions about this but I would like to share my opinion and maybe reopen this debate just to make sure the reasons why we have this still remain

I think only displaying the more modern version of the code (JSX , ESNEXT ...) in the code examples (with proper explanations to include others stacks) should be enough. IMO documentation should be opinionated to guide the user and simplify the number of decisions they have to take when using the information read in the docs.

The recommendation to create a block is to use the @wordpress/create-block that includes the tools to build the block and transpile the code from ESNext to ES5 with easy scripts and ver good documentation about it. Isn't this enough to display only the code that works with this setup?

Being aware that there are a lot of developers that are not comfortable with JS setup tools and that they prefer working w/ ES5 directly and no build process. Has this been measured somehow? I mean, is this a majority of people? Compared to what? How do the ones that prefer ES5 code develop blocks?

We dropped support for IE 11 last year, so we no longer have to limit developers to use ES5 when they prefer to avoid using build tooling. That's why ESNext vs ES5 is no longer a good distinction. It's mostly whether someone wants to use JSX when using React components. Another bonus is when folks want to use some of the most recent language features that aren't still implemented in all browsers supported by WordPress. However, these days it's mostly about using JSX and more importantly about the additional tooling that helps to remove the maintenance burden from devs so they don't have to manually list script dependencies in PHP files, minify assets, handle CSS, and so on.

[ryanwelcher]

I've updated this issue to reflect that all of the blocks in the Gutenberg Examples repo are using block.json files.

Additionally, we have generated a new release ( 1.1.0 ) that has an updated .zip that can be installed as a plugin.

There is a lot of work/planning going into the examples to restructure it to allow for:

1. A single build process - Major structural overhaul to the repo gutenberg-examples#195
2. Using GitHub actions for linting new Pull Requests - Introduce action to lint new pull requests gutenberg-examples#193
3. Automate the release process

[juanmaguitar]

I think we could close this issue in favor of #55432
Any thoughts?

[gziolo]

I think we could close this issue in favor of #55432 Any thoughts?

I'm all in favor of starting with a fresh issue that has way better visibility into actionable items. This discussion was invaluable for recognizing the first steps, but after some time and many comments posted, it became hard to understand what's left and what's the top priority. @annezazu, does it work for you, too?

[annezazu]

Yes. Just was coming here to do exactly that. Closing now!