first version of the Interactivity API README #52104
Conversation
There was a problem hiding this comment.
Thanks, Juanma! This is a great start ❤️
Some comments:
Maybe the main thing people should notice when looking at this is that this package is still very experimental, and very likely to change. And we should put a prominent link to the Proposal and encourage participation in helping to shape the API by opening discussions in GitHub.
Also, maybe it's worth sharing that it is only available in Gutenberg at the moment and not in WordPress Core to avoid confusion.
In my opinion, these are the questions this Readme should aim to answer:
- What is this? This is the base of a new standard to create interactive blocks. Link to the Proposal.
- Can I use it? You can test it, but it's still very experimental.
- How do I get started? Link to the getting started guide
- Where can I ask questions? Link to the GH discussions
- Where can I share my feedback about the API? Link to the GH discussions
@juanmaguitar: What do you think?
packages/interactivity/README.md
Outdated
|
|
||
| _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._ | ||
|
|
||
| ## Usage |
There was a problem hiding this comment.
I'm not sure a Usage section adds value or rather confusion. This is not like most of the packages, where you want to know how to use the most common API right away. This package requires you to understand what directives are available, how to add them to your HTML and how to link them with references.
Maybe instead of adding all that information here, we should just point to the getting started guide? I know we don't have any yet, but we can leave a message that we're working on it and update it once we have it.
What do you think?
| Interactivity API is a recent proposal and its Documentation is still in progress. In the meantime, here you have these resources to learn/read more about the Interactivity API: | ||
|
|
||
| - [Proposal: The Interactivity API – A better developer experience in building interactive blocks](https://make.wordpress.org/core/2023/03/30/proposal-the-interactivity-api-a-better-developer-experience-in-building-interactive-blocks/) | ||
| - [“Interactivity API” category](https://github.com/WordPress/gutenberg/discussions/categories/interactivity-api) in Gutenberg repo discussions |
There was a problem hiding this comment.
I would make this more prominent. I don't know, maybe even a new top section called "## Questions" so we say again that the documentation is still in progress and encourage people to ask as many questions as they want.
packages/interactivity/README.md
Outdated
|
|
||
| ## Contributing to this package | ||
|
|
||
| This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects. |
There was a problem hiding this comment.
and used by WordPress
I know this is a general message, but I don't know if we should exclude this part for now, to avoid confusion.
|
Flaky tests detected in 3fb8e70. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/5409677445
|
|
Thanks a lot for your feedback @luisherranz |
* first version of the Interactivity API README * README v2 upon Luis feedback * headings adjusted * minor adjustments
luisherranz
added
[Feature] Interactivity API
What?
A first version of the README.md for the Interactivity API package
Why?
Because this package needs a good reference for developers using it
How?
By creating this README and adding relevant info for developers in it