Docs: Improve the learning experience for writing blocks #49792
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
gziolo
requested review from
ajitbohra,
ryanwelcher,
juanmaguitar and
fabiankaegy
as code owners
gziolo
added
[Feature] Block API
|
Size Change: 0 B Total Size: 1.37 MB ℹ️ View Unchanged
|
priethor
approved these changes
Apr 13, 2023
mburridge
reviewed
Apr 13, 2023
| @@ -16,169 +18,6 @@ npm install @wordpress/blocks --save | |||
|
|
|||
| _This package assumes that your code will run in an **ES2015+** environment. If you're using an environment that has limited or no support for such language features and APIs, you should include [the polyfill shipped in `@wordpress/babel-preset-default`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/babel-preset-default#polyfill) in your code._ | |||
|
|
|||
| ## Getting Started | |||
There was a problem hiding this comment.
This is actually quite a nice tutorial. I appreciate that this is probably not the right place for it as it's quite hard to find as it's buried deep in the docs. It would be nice to retain it in some form though. Either move it to the Getting Started section as an alternative tutorial, or use this content as the basis of a 'Write your first block' post on the Developer Blog.
There was a problem hiding this comment.
This tutorial is outdated. It was authored in 2017, and everything has changed since then. We can bring it back in a different place as a follow-up after applying all necessary edits, so it plays its purpose correctly.
There was a problem hiding this comment.
Agreed with both; it would be nice to have it up to date and in a better location, but that's outside the scope of this PR.
There was a problem hiding this comment.
Yes, the code needs updating, but the explanations have a clarity that I think make it worth retaining. It would be nice to re-work it and re-purpose it elsewhere. That's all I'm saying.
I also think that the example project here is nicer and more functional than the Getting Started one, which is a bit rudimentary and the font used only works in Firefox.
There was a problem hiding this comment.
use this content as the basis of a 'Write your first block' post on the Developer Blog.
That sounds like a good idea.
I also think that the example project here is nicer and more functional than the Getting Started one, which is a bit rudimentary and the font used only works in Firefox.
In some ways, it's better, but still, it isn't good enough for what we want to promote these days:
- block supports usage for global styles is not covered, it would probably be better than all the hassle with CSS files
- we should start promoting dynamic blocks, or even better hybrid blocks, where we use
saveas the fallback for the block, but we still enrich the content with PHP - in a few months, the tutorial should also cover how to make blocks interactive on the front end
That's a very interesting topic we should discuss as the block editor handbook evolves. There is value in keeping Create Block Tutorial simple, so it won't be simple to find the sweet spot. The interesting part is that some of the How-To Guides could fill in the complete picture of block development and extend the block crafted in the tutorial with additional functionalities.
I changed that only because all items in the sidebar menu are sorted by page’s slug name and the labels follow that with the exception of Block Templates. I can revert that part and live with that 😂 |
mburridge
reviewed
Apr 13, 2023
|
@gziolo Makes sense; then I'd opt for your other alternatives like just |
juanmaguitar
approved these changes
Apr 13, 2023
"Block Templates" has always been a confusing topic for the community. We are talking about "templates for blocks" here as opposed to "building templates out of blocks". I do think simplifying the title to |
gziolo
force-pushed
the
update/docs-create-block
branch
from
8855899 to
ddce27c
Compare
gziolo
commented
Apr 14, 2023
gziolo
commented
Apr 14, 2023
|
I updated all occurrences of “Templates for Blocks” to “Templates” as suggested. Thank you for the feedback 🙇🏻 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What?
Fixes #48638.
Improves the learning experience for writing blocks by making the documentation more consistent and clear where to find information about writing blocks.
Why?
To make the learning experience for folks starting with block development less confusing.
How?
@wordpress/blockspackage and replace with the callout to check Create Block Tutorial: