Document how developers can use block editor notices

[danielbachhuber]

Following up on the conversation in #11604 (comment), developers would benefit from some documentation on how to use block editor notices.

I've started a draft in this Dropbox Paper document: https://paper.dropbox.com/doc/Using-notices-in-the-block-editor--AWl6LauVA0RqsUxyGQBY~W~dAg-PlWYEgAxvNn1e4ul5Ba42

Feel free to leave comments directly. Or, if you'd like to help collaborate, ping me on WordPress.org Slack with your Dropbox account email address.

Once this document is in a mostly final state, I'll submit it as a pull request to wherever it needs to go.

[danielbachhuber]

Now that I have a full draft in my Dropbox Paper document, I'm not quite sure where this would fit. Any suggestions?

[aduth]

I could imagine one of either:

• As a new section in Tutorials
  • https://wordpress.org/gutenberg/handbook/designers-developers/developers/tutorials/
  • Maybe a set of "Data Access" examples tutorials?
• In the documentation of the @wordpress/notices package
  • https://wordpress.org/gutenberg/handbook/designers-developers/developers/packages/packages-notices/

[danielbachhuber]

@chrisvanpatten Do you have any preference, or know who might have an opinion?

[danielbachhuber]

@youknowriad Could I get some final determination? I'd love to get this landed.

[danielbachhuber]

I could also just publish it to my blog, if it's not entirely appropriate for WordPress.org

[youknowriad]

My personal preference would be a tutorial.

[chrisvanpatten]

@danielbachhuber Sorry just seeing my tag (started a new job and still catching up w/ life haha). I think in the tutorials section is appropriate!

[aduth]

As a continuation of #13593, I'd propose the issue here account for:

• Consistency across modules which provide some data store, as far as documenting access to data behaviors (viewport is a similar "data-only" module, but same could be applied to any module's store)
• Clarification that the data store is only registered if defined as a dependency to one's script
• Clarification that dispatch is intended for effecting change, and including reference to data retrieval (i.e. select in addition to just a reference to dispatch).

I wonder if, for these modules, it might make sense to have a section specifically dedicated to usage in a WordPress context. Cordoning off in this way could prove to be a reasonable compromise between usefulness to a WordPress developer and respect toward the fact that these modules are published as standalone to npm.

Example:

## Usage in WordPress

In WordPress, the [x] module is [registered](https://developer.wordpress.org/reference/functions/wp_register_script/) using the `wp-[x]` script handle. When enqueuing your own scripts which make use of the [x] module, be sure to define this as a dependency.

In your JavaScript scripts, the public interface of the module can be referenced on the `window` global via `wp.[x]`.

To access [data methods](https://wordpress.org/gutenberg/handbook/designers-developers/developers/packages/packages-data/#data-access-and-manipulation) provided through the [x] module's registered store, reference it via the `core/[x]` namespace:

```js
wp.data.select( 'core/[x]' );
wp.data.dispatch( 'core/[x]' );
```

[danielbachhuber]

@aduth Can you create a new issue? That seems like a much broader scope that I don't feel comfortable owning.

Related to this, would you like to land the document I've already created, or do you want to hold off until the broader scope is addressed?

[aduth]

@aduth Can you create a new issue? That seems like a much broader scope that I don't feel comfortable owning.

#13674