Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation: Add block submission guidelines. #23545

Merged
merged 23 commits into from
Aug 10, 2020

Conversation

StevenDufresne
Copy link
Contributor

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

@StevenDufresne StevenDufresne added [Type] Developer Documentation Documentation for developers [Feature] Block Directory Related to the Block Directory, a repository of block plugins labels Jun 29, 2020
@github-actions
Copy link

github-actions bot commented Jun 29, 2020

Size Change: -1.01 MB (87%) 🏆

Total Size: 1.15 MB

Filename Size Change
build/a11y/index.js 0 B -1.14 kB (0%)
build/annotations/index.js 0 B -3.62 kB (0%)
build/api-fetch/index.js 0 B -3.4 kB (0%)
build/autop/index.js 0 B -2.82 kB (0%)
build/blob/index.js 0 B -620 B (0%)
build/block-directory/index.js 0 B -7.39 kB (0%)
build/block-directory/style-rtl.css 944 B +3 B (0%)
build/block-directory/style.css 945 B +3 B (0%)
build/block-editor/index.js 0 B -109 kB (0%)
build/block-editor/style-rtl.css 10.8 kB +107 B (0%)
build/block-editor/style.css 10.8 kB +101 B (0%)
build/block-library/editor-rtl.css 7.61 kB +16 B (0%)
build/block-library/editor.css 7.61 kB +13 B (0%)
build/block-library/index.js 0 B -130 kB (0%)
build/block-library/style-rtl.css 7.82 kB -215 B (2%)
build/block-library/style.css 7.83 kB -215 B (2%)
build/block-library/theme-rtl.css 728 B -2 B (0%)
build/block-library/theme.css 729 B -3 B (0%)
build/block-serialization-default-parser/index.js 0 B -1.88 kB (0%)
build/block-serialization-spec-parser/index.js 0 B -3.1 kB (0%)
build/blocks/index.js 0 B -48.2 kB (0%)
build/components/index.js 0 B -198 kB (0%)
build/components/style-rtl.css 15.7 kB -245 B (1%)
build/components/style.css 15.6 kB -242 B (1%)
build/compose/index.js 0 B -9.65 kB (0%)
build/core-data/index.js 0 B -11.4 kB (0%)
build/data-controls/index.js 0 B -1.29 kB (0%)
build/data/index.js 0 B -8.44 kB (0%)
build/date/index.js 0 B -5.47 kB (0%)
build/deprecated/index.js 0 B -772 B (0%)
build/dom-ready/index.js 0 B -569 B (0%)
build/dom/index.js 0 B -3.19 kB (0%)
build/edit-navigation/index.js 0 B -9.87 kB (0%)
build/edit-navigation/style-rtl.css 1.08 kB +58 B (5%) 🔍
build/edit-navigation/style.css 1.08 kB +58 B (5%) 🔍
build/edit-post/index.js 0 B -303 kB (0%)
build/edit-post/style-rtl.css 5.61 kB +104 B (1%)
build/edit-post/style.css 5.61 kB +103 B (1%)
build/edit-site/index.js 0 B -16.7 kB (0%)
build/edit-site/style-rtl.css 3.06 kB +25 B (0%)
build/edit-site/style.css 3.06 kB +26 B (0%)
build/edit-widgets/index.js 0 B -9.32 kB (0%)
build/edit-widgets/style-rtl.css 2.45 kB +26 B (1%)
build/edit-widgets/style.css 2.45 kB +26 B (1%)
build/editor/index.js 0 B -44.8 kB (0%)
build/editor/style-rtl.css 3.78 kB -64 B (1%)
build/editor/style.css 3.78 kB -70 B (1%)
build/element/index.js 0 B -4.65 kB (0%)
build/escape-html/index.js 0 B -733 B (0%)
build/format-library/index.js 0 B -7.72 kB (0%)
build/hooks/index.js 0 B -2.13 kB (0%)
build/html-entities/index.js 0 B -622 B (0%)
build/i18n/index.js 0 B -3.56 kB (0%)
build/is-shallow-equal/index.js 0 B -711 B (0%)
build/keyboard-shortcuts/index.js 0 B -2.51 kB (0%)
build/keycodes/index.js 0 B -1.94 kB (0%)
build/list-reusable-blocks/index.js 0 B -3.12 kB (0%)
build/list-reusable-blocks/style-rtl.css 476 B +26 B (5%) 🔍
build/list-reusable-blocks/style.css 476 B +25 B (5%) 🔍
build/media-utils/index.js 0 B -5.29 kB (0%)
build/notices/index.js 0 B -1.79 kB (0%)
build/nux/index.js 0 B -3.4 kB (0%)
build/nux/style-rtl.css 671 B +8 B (1%)
build/nux/style.css 668 B +8 B (1%)
build/plugins/index.js 0 B -2.56 kB (0%)
build/primitives/index.js 0 B -1.5 kB (0%)
build/priority-queue/index.js 0 B -788 B (0%)
build/redux-routine/index.js 0 B -2.85 kB (0%)
build/rich-text/index.js 0 B -14 kB (0%)
build/server-side-render/index.js 0 B -2.68 kB (0%)
build/shortcode/index.js 0 B -1.7 kB (0%)
build/token-list/index.js 0 B -1.28 kB (0%)
build/url/index.js 0 B -4.06 kB (0%)
build/viewport/index.js 0 B -1.85 kB (0%)
build/warning/index.js 0 B -1.14 kB (0%)
build/wordcount/index.js 0 B -1.17 kB (0%)
ℹ️ View Unchanged
Filename Size Change
build/a11y/index.min.js 1.14 kB 0 B
build/annotations/index.min.js 3.67 kB 0 B
build/api-fetch/index.min.js 3.43 kB 0 B
build/autop/index.min.js 2.82 kB 0 B
build/blob/index.min.js 620 B 0 B
build/block-directory/index.min.js 7.63 kB 0 B
build/block-editor/index.min.js 125 kB 0 B
build/block-library/index.min.js 132 kB 0 B
build/block-serialization-default-parser/index.min.js 1.88 kB 0 B
build/block-serialization-spec-parser/index.min.js 3.1 kB 0 B
build/blocks/index.min.js 48.3 kB 0 B
build/components/index.min.js 200 kB 0 B
build/compose/index.min.js 9.68 kB 0 B
build/core-data/index.min.js 11.5 kB 0 B
build/data-controls/index.min.js 1.29 kB 0 B
build/data/index.min.js 8.45 kB 0 B
build/date/index.min.js 5.38 kB 0 B
build/deprecated/index.min.js 772 B 0 B
build/dom-ready/index.min.js 568 B 0 B
build/dom/index.min.js 3.23 kB 0 B
build/edit-navigation/index.min.js 10.8 kB 0 B
build/edit-post/index.min.js 304 kB 0 B
build/edit-site/index.min.js 16.9 kB 0 B
build/edit-widgets/index.min.js 9.37 kB 0 B
build/editor/editor-styles-rtl.css 537 B 0 B
build/editor/editor-styles.css 539 B 0 B
build/editor/index.min.js 45.3 kB 0 B
build/element/index.min.js 4.65 kB 0 B
build/escape-html/index.min.js 733 B 0 B
build/format-library/index.min.js 7.72 kB 0 B
build/format-library/style-rtl.css 547 B 0 B
build/format-library/style.css 548 B 0 B
build/hooks/index.min.js 2.13 kB 0 B
build/html-entities/index.min.js 621 B 0 B
build/i18n/index.min.js 3.56 kB 0 B
build/is-shallow-equal/index.min.js 711 B 0 B
build/keyboard-shortcuts/index.min.js 2.51 kB 0 B
build/keycodes/index.min.js 1.94 kB 0 B
build/list-reusable-blocks/index.min.js 3.12 kB 0 B
build/media-utils/index.min.js 5.32 kB 0 B
build/notices/index.min.js 1.79 kB 0 B
build/nux/index.min.js 3.4 kB 0 B
build/plugins/index.min.js 2.56 kB 0 B
build/primitives/index.min.js 1.4 kB 0 B
build/priority-queue/index.min.js 789 B 0 B
build/redux-routine/index.min.js 2.85 kB 0 B
build/rich-text/index.min.js 13.9 kB 0 B
build/server-side-render/index.min.js 2.71 kB 0 B
build/shortcode/index.min.js 1.7 kB 0 B
build/token-list/index.min.js 1.27 kB 0 B
build/url/index.min.js 4.06 kB 0 B
build/viewport/index.min.js 1.85 kB 0 B
build/warning/index.min.js 1.14 kB 0 B
build/wordcount/index.min.js 1.17 kB 0 B

compressed-size-action

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This list is outdated, see: #19279

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This list was taken from the block-registration documentation. I'll update it there as well.

@paaljoachim paaljoachim mentioned this pull request Jun 30, 2020
3 tasks
- 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Include example data (optional, but useful).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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? :)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@itsjusteileen
Copy link
Contributor

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@annezazu
Copy link
Contributor

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 💥

@StevenDufresne
Copy link
Contributor Author

Can programmatic block templates aka 'inner blocks' also be included in the Block Directory? If so mention here would be noteworthy.

@StevenDufresne
Copy link
Contributor Author

Can programmatic block templates aka 'inner blocks' also be included in the Block Directory? If so mention here would be noteworthy.

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.

@StevenDufresne
Copy link
Contributor Author

@annezazu @itsjusteileen Very thankful for the reviews! :)

@StevenDufresne StevenDufresne reopened this Jul 1, 2020
Copy link
Member

@mkaz mkaz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have a few minor formatting tweaks, not a big deal.

This is good, I'm good with adding and iterating, this tutorial is not linked up yet, so it is a good to commit and add to.

👍

@StevenDufresne StevenDufresne marked this pull request as ready for review July 2, 2020 05:41

**Contents**:
1. Help users understand your block
2. Analyze your plugin
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Copy link
Contributor

@paaljoachim paaljoachim Jul 11, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here are some of my suggestions.

Share your Block

Contents:

  1. Help users understand your block
  2. 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.

@ryelle
Copy link
Contributor

ryelle commented Jul 9, 2020

I added more details about the block.json, including an example of a very simple block.json file in cb7e2e6


**Not So Good**: WebTeam5 Image Works
**Good**: Responsive Image Slider by WebTeam5

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.)

**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!

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think without that first sentence it would be hard to understand the context. I think It may be better to remove it instead.


## 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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@paaljoachim
Copy link
Contributor

paaljoachim commented Jul 11, 2020

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),
creating your first block plugin (EDIT: https://github.com/WordPress/gutenberg/tree/master/docs/designers-developers/developers/tutorials/create-block - This will be changed as the dev environment will first be merged.)
and then finally submit your block (which I will get to).

@StevenDufresne
Copy link
Contributor Author

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), then the creating your first block plugin (I do not know where the create a block docs is located right now - need to go through) and then finally submit your block (which I will get to).

Perfect. Thanks for the help!

@mkaz mkaz merged commit 0c80932 into master Aug 10, 2020
@mkaz mkaz deleted the add/block-directory-checklist branch August 10, 2020 23:06
@github-actions github-actions bot added this to the Gutenberg 8.8 milestone Aug 10, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
[Feature] Block Directory Related to the Block Directory, a repository of block plugins [Type] Developer Documentation Documentation for developers
Projects
None yet
Development

Successfully merging this pull request may close these issues.

10 participants