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.

• [X] 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. #22831
  • https://developer.wordpress.org/block-editor/getting-started/create-block/
• [X] Repurpose the Block Tutorial and Gutenberg workshop materials from @mkaz as the basis for the “Creating Blocks” tutorial. #22831
  • https://developer.wordpress.org/block-editor/getting-started/create-block/
• [X] 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. #23946
• [X] 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. #23946
• [X] Define more clearly what’s allowed for blocks (prior discussion) and include the outcome in the "Creating block" tutorial. #23545
• [X] Document the process for getting a single block plugin uploaded to the block directory as part of the creating a block tutorial. #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 https://github.com/WordPress/gutenberg/issues/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: https://github.com/WordPress/gutenberg/issues/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.

• [X] Incorporate @wordpress/create-block more clearly into the block tutorial. #22831

• [X] Remove WP-CLI references from the block tutorial. #23946

• [X] Clarify block.json (and perhaps autogenerate it #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: https://github.com/WordPress/gutenberg/issues/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.
• [x] 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 notifications@github.com 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]

:+1: Nope, I think a meeting note reference is perfect.

[StevenDufresne]

Document the process for getting a single block plugin uploaded to the block directory as part of the creating a block tutorial.

I have coincidentally put together a document that addresses this task (kind of). It's origin goal was to 'imagine' what it would be like to have a block plugin and be considering uploading it to the block directory to anticipate some technical/content challenges developers could face with the block directory. I could upload it for us to work on by committee.

If we are keen on that, where would it live? If not, no problem ;)

[annezazu]

Amazing! Thank you @StevenDufresne. I know @mkaz is working on a block tutorial so perhaps this can be added in as part of the work he is doing there?

[leoloso]

Hey everyone, I want to make one comment, with risk of sounding obvious: The best documentation is no documentation. I say this because of the tools that have been created to automate tasks, specifically:

• @wordpress/create-block
• wp-env
• (and possibly BlockBook, but it's too early to tell)

I must stress how important these are, particularly @wordpress/create-block. I will explain my own story, my relationship with these tools concerning building blocks.

I am a newbie developer with JS, coming from a PHP background. I had never used either webpack, npm, or React. And some 4 to 5 months ago I decided to fully rely on Gutenberg to operate my plugin.

When I started, I checked the documentation (not just from the GitHu repo, but also tutorials about Gutenberg all over the internet), and I was immediately lost. It's not necessarily that the documentation was bad. It's that the task at hand was very difficult, and I didn't have a lot of confidence in myself, being everything new. For instance, some tutorials mentioned how you first had to create your webpack configuration to create a block. I'm sorry, that's not for me. webpack is such an advanced tool, where everything can go wrong. And the Gutenberg documentation mentions the ES5 and ES6 code, and it was not clear to me which one to use, or why.

Luckily for me, this was roughly the same time when @wordpress/create-block was launched. I remember well, because I even wrote about it here:

As luck would have it, a new tool to scaffold Gutenberg blocks was released just a few days before my work started: the @wordpress/block package (also called @wordpress/create-block), which allows to create a new WordPress plugin containing all the necessary JavaScript, CSS and PHP files to register a block, with zero configuration.

It was love at first sight. Using this tool, most of my problems were gone, since it allowed me to not think how to set-up Gutenberg. It just did it for me. Once I created the project for a new Gutenberg block, I could then play with it, and then everything slowly fell in place.

(Not everything was perfect, though: My plugin has many blocks, and needs to set-up some panels on the Document TabPanel, which doesn't use blocks, so I had to hack the output from @wordpress/create-block to make it work. I've been talking to @gziolo about this)

Then, having the foundations that I needed, I managed to create my blocks (16 in total! 😲). I wrote down my experience in a few articles (this one, this one and this one... thanks @bph to share them 😀).

After my experience, my opinion is this one:

We shouldn't strive to provide the perfect documentation, since that will never happen:

• Writing documentation takes plenty of time
• The needs from all the developers (complete newbies, newbies, mid-level, experienced) are very different
• Can prioritize for newbies, but up to what level? For instance, should explain how to use npm each single time a JavaScript dependency must be installed? Or is that too much?

Moreover, Gutenberg keeps changing, and having to keep the documentation always up-to-date will be a major problem.

And finally, don't forget the famous RTFD 🙉.

Instead, if we make sure that there are tools that make it easy to the user to get started, and that guide the user in a meaningful way, then a huge barrier will go down.

For instance, for @wordpress/create-block, @gziolo told me it will support templates, so that we can create also scripts, not just blocks, and also multi-block plugins instead of single-block plugins. Then, instead of creating documentation, we can invest our energy into providing a set of very meaningful templates for many different situations.

I think that promoting @wordpress/create-block should be an upmost priority for the Gutenberg project.

Concerning wp-env, I also have a very good impression, because it makes it easy for potential contributors to start hacking away at the code immediately (and, for that reason, I use it in my plugin). Then, promoting wp-env among open source block developers could also be a good idea, as to lower down the barriers of installing the block, and then learning from its code.

(I assume that BlockBook can also help in this regard. Let's see how it goes.)

Please don't get me wrong. Documentation is extremely important. I'm not asking to not write documentation. What I say is that, if the tools obviate the need for the developer to understand how something is done (be it webpack, Babel, JSLint, or anything else) then it's a win-win for everyone: less frustration for the developer, less work for the documenters 🙏.

Conclusion: let's invest energy mostly in the tools that make it easy for users to get started. In the modern world of JavaScript, this is needed, or we'd quickly go insane with all new developments happening every week.

(Updated comment to remove shameless paragraph describing my plugin, I apologize about that, and fixed a few typos)

[leoloso]

I want to describe a situation I had, that just came to my mind, to justify my previous comment.

For a block in my plugin, I had to retrieve data from the API, so I had to implement a data store. I went to the corresponding package, @wordpress/data, and I read all about it, and I heeded its advice to read the core principles and glossary from Redux.

From a theoretical point of view, everything worked in my head, the idea of keeping the store stateless clicked immediately. But yet, when implementing the store in code, it was really hard, and it took me several days.

The README for @wordpress/data is very comprehensive. Yet, it is already not up-to-date, for instance:

• The demonstrated example uses const { registerStore } = wp.data;, when this has been discontinued in favor of import { registerStore } from '@wordpress/data';
• The code examples do not have the same file structure found in the codebase (at least not currently), which hinders doing some correlation between the theory and an actual implementation of it. The structure in the codebase looks like this:
  • store/actions.js
  • store/controls.js
  • store/index.js
  • store/reducer.js
  • store/resolvers.js

Next, there's nothing wrong with the documentation, because it's a very technical topic. But I remember very well, reading and re-reading these paragraphs below, without making much sense of it for quite a few days:

#### `resolvers`

A **resolver** is a side-effect for a selector. If your selector result may need to be fulfilled from an external source, you can define a resolver such that the first time the selector is called, the fulfillment behavior is effected.

The `resolvers` option should be passed as an object where each key is the name of the selector to act upon, the value a function which receives the same arguments passed to the selector, excluding the state argument. It can then dispatch as necessary to fulfill the requirements of the selector, taking advantage of the fact that most data consumers will subscribe to subsequent state changes (by `subscribe` or `withSelect`).

#### `controls`

A **control** defines the execution flow behavior associated with a specific action type. This can be particularly useful in implementing asynchronous data flows for your store. By defining your action creator or resolvers as a generator which yields specific controlled action types, the execution will proceed as defined by the control handler.

The `controls` option should be passed as an object where each key is the name of the action type to act upon, the value a function which receives the original action object. It should returns either a promise which is to resolve when evaluation of the action should continue, or a value. The value or resolved promise value is assigned on the return value of the yield assignment. If the control handler returns undefined, the execution is not continued.

And then, function * getPrice( item ), I didn't know what that * was for, and the documentation doesn't explain either.

Long story short: Just from reading the documentation, I could not create my data store.

So I searched online, and I found this example:

const actions = {
    setUserRoles( userRoles ) {
        return {
            type: 'SET_USER_ROLES',
            userRoles,
        };
    },
    receiveUserRoles( path ) {
        return {
            type: 'RECEIVE_USER_ROLES',
            path,
        };
    },
};

const store = registerStore( 'matt-watson/secure-block', {
    reducer( state = { userRoles: {} }, action ) {

        switch ( action.type ) {
            case 'SET_USER_ROLES':
                return {
                    ...state,
                    userRoles: action.userRoles,
                };
        }

        return state;
    },

    actions,

    selectors: {
        receiveUserRoles( state ) {
            const { userRoles } = state;
            return userRoles;
        },
    },

    controls: {
        RECEIVE_USER_ROLES( action ) {
            return apiFetch( { path: action.path } );
        },
    },

    resolvers: {
        * receiveUserRoles( state ) {
            const userRoles = yield actions.receiveUserRoles( '/matt-watson/secure-blocks/v1/user-roles/' );
            return actions.setUserRoles( userRoles );
        },
    },
} );

This was exactly my use case, which is as simple as it can be: to fetch data from a URL. If the @wordpress/data doc simply had this case, I would've saved a few days.

Yet, this example also has a problem: action receiveUserRoles and selector receiveUserRoles have the same name, yet there is no need for that. So it becomes extremely confusing. Check out the resolver:

* receiveUserRoles( state ) {
    const userRoles = yield actions.receiveUserRoles( ... );

What is that first receiveUserRoles? And the second one? My brain becomes spaghetti trying to make sense of it.

But one day I figured it out, and I was able to create my store, replicating the file structure used in the Gutenberg codebase, and having non-duplicate names. The result is here.

And so, what happened then? It was ready! As I mentioned, I created 16 blocks, and several of them needed a store. But then, I could copy/paste this original one, and modify the names of the functions, and voilà, the new block would have its own store in a couple of minutes.

---

Now, imagine if we could use @wordpress/create-block to create a simple data store through some template called dataStore. In this case, I'm overriding the meaning of this package: create-block could also append-code-to-an-existing-block. Then, on executing the template, it would create the file structure of the data store and save these files within the block, generating code that follows the most up-to-date conventions used in the codebase, and containing generic names for all the resolvers/reducers/selectors/etc for a simple search/replace by the developer.

Having this initial set-up, only then the developer worries about documentation. A huge step forward.

You may think that it's impossible to code all templates, for all use cases. But there's no need for that: only coding the most basic ones can go a long stretch, and they will be most helpful for beginners. The example I just mentioned is so basic, that it may solve already 50% of all requirements of data stores. And then, a second one called dataStoreWithDispatch could solve an additional 20%.

This could be similar to the WP-CLI scaffold command. Or Laravel's artisan command, which is extremely popular with the Laravel community.

[leoloso]

I combine my previous 2 comments into an actionable suggestion:

• Write documentation (I didn't say not to! Only to reasses its priority)
• At the same time, create templates to scaffold the different functionalities through @wordpress/create-block (for which, it must first support adding code to an existing block... I believe that's not the case yet)
• The documentation for some functionality should mention: "You can adding this functionlity to your block by: running npx @wordpress/create-block --template=dataStore (or something like that)

I think this strategy is sensible, because, as I mentioned, the documentation for @wordpress/data is very comprehensive, explaining how the concepts work for the developer to understand them. However, it is already out-of-date, and it was not good enough for me to actually add the functionality to my block.

But then, if I create the scaffolding for the data store files using with @wordpress/create-block, it doesn't matter so much if the documentation says const { registerStore } = wp.data; because the tool will nevertheless create it the way it must be, as import { registerStore } from '@wordpress/data';. So the tool acts to make out-of-date documentation less of an issue.

This strategy is not ideal, we all love good documentation. But I think it's realistic, because Gutenberg is so complex, and it changes so often, that achieving perfect documentation, always up-to-date, is nearly impossible.

[bph]

Ideas of implementing additional templates for create-block tool as basis for example block building tutorials:

• dynamic block - scaffolding for server-side php rendering function
• options + display block - scaffolding - server-side php rendering, wp-options.php and rest-api-custom-endpoint.php + sidebar settings input.
• parent-child block - scaffolding for block-context and nested blocks.

[mrleemon]

What about people that don't want to create a block, but need to convert an old plugin which registers a custom post type with some fields inside a metabox to use the new editor UI? This use case is nowhere to be found in the current documentation, as it's only focused on creating blocks.

A visual example:

[skorasaurus]

What about....

@mrleemon

Check out https://github.com/10up/slotfill-and-filter-demos/ and https://ryanwelcher.com/2020/02/restricting-plugindocumentsettingpanel-by-post-type/

(this need is also documented at https://github.com/WordPress/gutenberg/issues/19747 https://github.com/WordPress/gutenberg/issues/17281

[emilio-martinez]

I like @bph's idea of multiple templates. In fact, on our projects we've setup our own scaffolding tooling (not using create-block) to meet aid in the creation and maintenance of the blocks we create.

To expand on the topic of maintenance, there are projects (like Nrwl's Nx) that have integrated code migrations as part of their upgrade tooling. Things like that, in my opinion, may be critical to problem space, particularly at a time where the Gutenberg APIs keep evolving.

Personally, our "documentation" so far has relied on observing the patterns used in the wordpress/gutenberg repo as it's changed across time 😶 but it's definitely not a scalable solution for everyone lol

[annezazu]

Jumped on a Learn WordPress discussion group this morning led by @jonathanbossenger <3 and wanted to loop back to underline how having more documentation for converting existing plugins to blocks would be incredibly helpful. Obviously, every use case can't be covered but giving some context and best practices for how to approach converting seems needed. This isn't listed in the core issue above.

Tied to this, the topic of wanting more documentation around how to handle customization came up too with one person sharing that the current docs allow you to get started in a basic way but drops off when it comes to customizing a block.

@mkaz as someone who has taken on many of these updates and has a great understanding of the codebase, what do you think might be a reasonable add considering the above? I can edit the original issue to include relevant new sections :)

[helgatheviking]

Hey y'all! Glad to see there is work going into the docs, because I fall into one of those personals... experienced WP dev who doesn't know anything about blocks.

One request... I know the block generating script is set up to magically work, but I'd love to see some more docu on how to modify the webpack. config settings so the generation script can be tweaked. I think I found the start and build params, eventually, but think there could be more detail and more navigation to guide me to that.

[leoloso]

It just hit me a sudden realization: Couldn't the Gutenberg docs have the same system of user feedback as the WordPress developer reference? There, anyone can leave helpful pieces of documentation, and, equally importantly, everyone else can up/downvote it.

For instance: https://developer.wordpress.org/reference/functions/register_setting/#user-contributed-notes

This system makes it easy for anyone to contribute some documentation, about whatever they think is important, so it's a bottom-up approach. This doesn't replace having a proper planning for documentation (as is intended in this issue), but it would certainly help. (In my case, the user-contributed notes told me exactly what I needed to know in quite a few opportunities.)

The Gutenberg docs are in markdown, and are precompiled. Could this dynamic functionality be still somehow added to the static page? (Eg: maybe an iframe? maybe use JS to fetch the data with an API and then render it dynamically?)

If you think this comment is off-topic, but it still makes sense, I can create it as a separate issue.

[annezazu]

@leoloso just to follow up -- I think this is a great item as a separate issue. It's been on my mind too to see what it would take to get the Gutenberg docs that aren't automatically generated moved to the Make network. Start the issue and we can all join you in discussing!

[leoloso]

Alright, will do! 😃

[skorasaurus]

related: https://github.com/WordPress/gutenberg/issues/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 (https://github.com/WordPress/gutenberg/pull/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 https://github.com/WordPress/gutenberg/issues/22151#issuecomment-859462352:

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 https://github.com/WordPress/gutenberg/issues/22151#issuecomment-912029825:

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 https://github.com/WordPress/gutenberg/issues/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'