Gutenberg: Documentation/Tutorial issues/enhancements

[rosswintle]

I just chatted to Tammie at WordCamp London where she encouraged me to open an issue.

Overview of issue

The docs seem incomplete and confusing for developers coming to the handbook to work out how to create a custom block for the first time.

Background

I confess that I've never actually created a block. Rather then use one of the existing scaffolds/boilerplates I decided I'd try starting by writing a simple plugin that used ES5 JS to create a simple block.

I thought I'd find the information I needed to do this in the Handbook. But I quickly ran into dead ends and realised that the handbook does not currently help someone do this (perhaps this is a not what the handbook is intended for?)

(Some) specific issues

1. I see no reference to or documentation of the enqueue_block_editor_assets and enqueue_block_assets hooks
2. This page sells itself as a tutorial, but it really isn't
3. The page linked above links to the Extensibility page which then links to the Tutorial, sending you round in a loop.
4. The footer next/prev (or possibly the sidebar nav) is broken in some places (e.g. at the bottom of this page, "Templates" does not exist in the sidebar nav on the left
5. There seems to be a PHP register_block_type function that is shown on this page but that doesn't seem to be in the block API (because it's probably not part of the block API as such) or in the reference section

Questions/what next?

I decided to open this rather than to dive into creating PRs because I'm not sure just going and adding/changing a load of stuff at this point is the right thing to do.

Questions then:

1. Is this handbook under review or being updated by someone else at the point? Does someone else have responsibility for updating the handbook? Or if I made a bunch of PRs are they likely to be accepted?
2. Is it worth doing this NOW or should I wait until the APIs are settled. If I updated the "tutorial" now would it soon be out of date?
3. Is the Handbook even the right place for a tutorial, or are you happy with the community writing tutorials on their own sites and linking the handbook off to them?

Thanks

[mrleemon]

Agreed. The documentation at least needs a STEP-BY-STEP tutorial on how to build a plugin that registers a simple custom block using both ES5 and ES6.

[gziolo]

This page sells itself as a tutorial, but it really isn't

https://wordpress.org/gutenberg/handbook/blocks/ is a tutorial but as you noted, the links on the bottom are broken :( cc @pento
See links on the left:

All those subpages listed on the left side help you to create blocks using ES5 and ES.next.

Agreed. The documentation at least needs a STEP-BY-STEP tutorial on how to build a plugin that registers a simple custom block using both ES5 and ES6.

This is already covered as noted above. We need to improve on page navigation.

There seems to be a PHP register_block_type function that is shown on this page but that doesn't seem to be in the block API (because it's probably not part of the block API as such) or in the reference section

It is part of the API. It is required to properly register a dynamic block. The one that is rendered on the server using render_callback.

Is this handbook under review or being updated by someone else at the point? Does someone else have responsibility for updating the handbook? Or if I made a bunch of PRs are they likely to be accepted?

I'm not aware of anyone responsible for this handbook other than all of us :) So every PR that improves the docs is more than expected.

Is it worth doing this NOW or should I wait until the APIs are settled. If I updated the "tutorial" now would it soon be out of date?

At this stage we don't plan to change APIs. There might be very subtle refinements, but you should consider everything stable.

Is the Handbook even the right place for a tutorial, or are you happy with the community writing tutorials on their own sites and linking the handbook off to them?

Yes, sure. There is even section where such links are listed: https://wordpress.org/gutenberg/handbook/outreach/articles/#community-contribution and https://wordpress.org/gutenberg/handbook/outreach/articles/#article-compilations

I didn't covered all questions, but I hope I helped where I could. Thanks for opening this issue 👍

[pento]

I fixed the ordering of the previous/next footer links: https://meta.trac.wordpress.org/changeset/7118

[rosswintle]

Ah. OK. So, I'm gonna raise my hand ✋ and say that I got confused here because of a change that seems to have happened since I last tried to create a block: it looks like the PHP register_block_type function has replaced the use of the enqueue_block_editor_assets and enqueue_block_assets hooks. register_block_type seems to have been around since v0.6 so not sure why so many block building tutorials (e.g. this and Ahmad's Boilerplate ) seem to reference the enqueue_* hooks

Realising this has certainly helped, as has @pento's change (thank you!). So my specific issues 2, 3, and 4 have all been fixed by this, I think.

[register_block_type] is part of the API. It is required to properly register a dynamic block. The one that is rendered on the server using render_callback.

I can't see this function documented anywhere (yet?). Have I missed it? Does it need adding?

I also find the API page really hard to navigate and digest. The visual hierarchy really doesn't aid comprehension. The first few paragraphs demonstrate this...

I'll try to take some time to make some PRs for some of this. But someone else may need to do some work on the API documentation design/styling - is this auto-generated from code at all?

Thanks - we are making this better! 👍

[gziolo]

I'll try to take some time to make some PRs for some of this. But someone else may need to do some work on the API documentation design/styling - is this auto-generated from code at all?

Gutenberg handbook is manually crafted using markdown and converted to HTML using some tooling on WordPress.org. There is a plan to introduce other docs for code which would be machine-generated.

[gziolo]

it looks like the PHP register_block_type function has replaced the use of the enqueue_block_editor_assets and enqueue_block_assets hooks. register_block_type seems to have been around since v0.6 so not sure why so many block building tutorials (e.g. this and Ahmad's Boilerplate ) seem to reference the enqueue_* hooks

The issue is with community tooling which isn't updated with the recent recommendations in Gutenberg handbook. register_block_type helps to keep implementation details of usingenqueue_block_editor_assets and enqueue_block_assets hidden for the plugin developer. They still can use it, but it is reserved for very advanced use cases. Otherwise, it should be enough to use register_block_type.

[chrisvanpatten]

As a note we'd like to include this in the new designer/dev handbook. If anyone wants to step up to write this tutorial, that would be super cool :)

[mkaz]

I think this issue is old and not actionable in the current state.
There now exists two tutorials which cover almost all of the above with examples and explanations

• Getting Started with JavaScript

• Block Tutorial

The auto generation of documentation looks to be addressed in PR #13329 by @nosolosw

So I think the main problems raised in this Issue have been or will be addressed. I'm going to mark as closed and please reopen, or add new issues if there is something I missed that still needs addressing. I'll be glad to help.