Documentation: Add block submission guidelines. #23545
Conversation
StevenDufresne
added
[Type] Developer Documentation
|
Size Change: -1.01 MB (87%) 🏆 Total Size: 1.15 MB
ℹ️ View Unchanged
|
| Gutenberg allows you to indicate which category your block fits in. Choosing the right category makes it easy for users to find in the Gutenberg menu. | ||
|
|
||
| **Possible Values**: | ||
| - Common |
There was a problem hiding this comment.
This list is outdated, see: #19279
There was a problem hiding this comment.
This list was taken from the block-registration documentation. I'll update it there as well.
| - Choose the right category | ||
|
|
||
| ### Name your block based on what it does | ||
| Users typically search the block directory within gutenberg and do so in the context of a task. For example, when building their post, a user may search the Block Directory for an “image gallery”. Naming your block accordingly will help the Block Directory surface it when it's needed. |
There was a problem hiding this comment.
Remove gutenberg in favor of block editor or editor window
"Users typically search the block directory directly from the editor, doing so when actively editing a post. For example, a user may search...
| `editorStyle` is pointing to the CSS bundle that includes all the css used in the **editor**. | ||
| `script` is pointing to the JavaScript bundle that includes all the code used on the **website**. | ||
| `style` is pointing to the CSS bundle that includes all the code used on the **website**. | ||
| I have included example data (Optional, but useful) |
There was a problem hiding this comment.
Include example data (optional, but useful).
There was a problem hiding this comment.
I changed it to Includes example data (optional, but useful). because it makes more sense in the context of the Double check that the following is true for your block. It feels more natural to me. I could be wrong though? :)
There was a problem hiding this comment.
I had to read this multiple times before I realized this meant the example property in block.json. I thought it was a note to yourself to come back and add example data 😅
Is the example data a requirement (or do we think it will be a requirement in the future)? We should either explain this better or drop it, IMO
| [Read more](https://github.com/WordPress/gutenberg/blob/master/docs/rfc/block-registration.md#keyword) about keywords. | ||
|
|
||
| ### Choose the right category | ||
| Gutenberg allows you to indicate which category your block fits in. Choosing the right category makes it easy for users to find in the Gutenberg menu. |
There was a problem hiding this comment.
The Block Editor allows you to indicate the category your block belongs in, making it easier for users to locate your block in the menu.
|
Can programmatic block templates aka 'inner blocks' also be included in the Block Directory? If so mention here would be noteworthy. |
| @@ -0,0 +1,88 @@ | |||
| #Share your Gutenberg Block with the World | |||
| So you’ve created an awesome block have you? Care to share? Here is some basic information on how to submit a block to the Block Directory. | |||
There was a problem hiding this comment.
I would just say simply: "So you've created an awesome block? Care to share?"
| #Share your Gutenberg Block with the World | ||
| So you’ve created an awesome block have you? Care to share? Here is some basic information on how to submit a block to the Block Directory. | ||
|
|
||
| Need help building a block? Check out our block tutorials to get started. |
There was a problem hiding this comment.
I would directly link to the documentation for block creation: https://github.com/WordPress/gutenberg/tree/master/docs/designers-developers/developers/tutorials/create-block
There was a problem hiding this comment.
I actually removed this line with the expectation that this document will tie closely into the Finishing Touches document and therefore may not be necessary. #23484.
I'll add it back in later if we think it necessary.
|
Just looked this over! I'm curious where people could go to get help if they get stuck in the submission process. If that's something that can be defined right now, I think it would be super helpful to include. In theory, doing so, should help get more feedback to you all about what blockers there are for submitting to the directory and increase the chances someone will complete a block directory submission 💥 |
|
This seems like it would be a technical details of creating a block. This document wasn't designed to be take on the technical details of a block directory block but I can see how that needs to live somewhere and right now it doesn't. |
|
@annezazu @itsjusteileen Very thankful for the reviews! :) |
docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md
Outdated
Show resolved
Hide resolved
docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md
Outdated
Show resolved
Hide resolved
docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md
Outdated
Show resolved
Hide resolved
docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md
Outdated
Show resolved
Hide resolved
docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md
Outdated
Show resolved
Hide resolved
docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md
Show resolved
Hide resolved
docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md
Show resolved
Hide resolved
docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md
Outdated
Show resolved
Hide resolved
docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md
Outdated
Show resolved
Hide resolved
|
|
||
| **Contents**: | ||
| 1. Help users understand your block | ||
| 2. Analyze your plugin |
There was a problem hiding this comment.
What do you think about renaming this section to "Provide data to the block directory"? Something about "Analyze your plugin" makes it sound automated, rather than curating data and describing your block(s)
There was a problem hiding this comment.
Here are some of my suggestions.
Share your Block
Contents:
- Help users understand your block
- Analyze your plugin? --> What does that mean? Using basic words to explain what it is.
Does this mean explain what your plugin does? Explain how you made your plugin?
I would skip the use of the word awesome as it has really no meaning/purpose in a tutorial.
The user needs to figure out for themselves if their plugin is awesome and then have a need/want to share it with others.
@ryelle Kelly
Curating data I really do not understand what that means.
|
I added more details about the block.json, including an example of a very simple block.json file in cb7e2e6 |
docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md
Show resolved
Hide resolved
|
|
||
| **Not So Good**: WebTeam5 Image Works | ||
| **Good**: Responsive Image Slider by WebTeam5 | ||
|
|
There was a problem hiding this comment.
It is very helpful to have additional examples.
|
|
||
| **Question: What happens when there are multiple blocks with similar names?** | ||
| Try your best to make your block's name functional and unique to make it stand out. Look for applicable synonyms or include a prefix if necessary. | ||
|
|
There was a problem hiding this comment.
Here it would be good to just mention that it is good to include a prefix. (Regarding the conversation above this might be changed to remember to include a prefix.)
docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md
Show resolved
Hide resolved
| **Good**: An easy to use, responsive, Image gallery block. | ||
|
|
||
| **Tip**: It’s not about marketing your block, in fact we want to avoid marketing in blocks. You can read more about it in the [plugin guidelines]. Stick to being as clear as you can. The block directory will provide metrics to let users know how awesome your block is! | ||
|
|
There was a problem hiding this comment.
The above is not clear for me.
I would skip the first sentence, and instead add something like the below.
You can read more about marketing your block in the plugin guidelines. The Block Directory will provide metrics to let users know helpful your block is.
There was a problem hiding this comment.
I think without that first sentence it would be hard to understand the context. I think It may be better to remove it instead.
docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md
Show resolved
Hide resolved
|
|
||
| ## Step 2: Analyze your plugin | ||
| Each block in your plugin should have a corresponding `block.json` file. This file provides the Block Directory important information about your block. Along with being the place to store contextual information about your block like the: `name`, `description`, `keywords` and `category`, the `block.json` file stores the location of your block’s files. | ||
|
|
There was a problem hiding this comment.
Each block in your plugin needs to have a corresponding block.json file. This file provides important information about your block to the Block Directory.
What important information? Go straight to the point and give the details without it saying the word important. The files stores such and such information. Give a detailed overview of what the json file stores.
Kinda like.
The block.json file stores the location of your block's files as well as contextual information like the: name, description, keywords and category. In addition is also stores.....?
| Each block in your plugin should have a corresponding `block.json` file. This file provides the Block Directory important information about your block. Along with being the place to store contextual information about your block like the: `name`, `description`, `keywords` and `category`, the `block.json` file stores the location of your block’s files. | ||
|
|
||
| Block plugins submitted to the Block Directory can contain mutliple blocks only if they are children of a single parent/ancestor. There should only be one main block. For example, a list block can contain list-item blocks. Children blocks must set the `parent` property in their `block.json` file. | ||
|
|
There was a problem hiding this comment.
Block plugins submitted to the Block Directory can contain multiple (typo) blocks only if they are children of a single parent/ancestor.
Rephrasing.
Block plugins submitted to the Block Directory should have one main block, but it can contain multiple child blocks.
For example, a list block can contain list-item child blocks. Child blocks must set the parent property in their block.json file.
docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md
Show resolved
Hide resolved
docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md
Show resolved
Hide resolved
docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md
Outdated
Show resolved
Hide resolved
docs/designers-developers/developers/tutorials/create-block/submitting-to-block-directory.md
Show resolved
Hide resolved
|
Keep the language as simple and neutral as possible. A neutral narrator voice. Long sentences should likely be cut in two. Remember that people from all over the world with different English reading skills will be going through the documentation. Block Directory = Capital B and capital D. General adjustment through the documentation. Ps When ready we need someone to go through the steps in a practical way. I will likely do so but I am following the steps of creating a local dev environment (#23593 still being worked on), |
Perfect. Thanks for the help! |
Description
This PR exposes documentation to help block developers submit blocks to the block directory in the hope of getting more collaboration. The end document doesn't need to live where this PR proposes it.
This PR is associated to #23484