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.