search

WordPress / gutenberg

The Block Editor project for WordPress and beyond. Plugin is available from the official repository.
https://wordpress.org/gutenberg/
Other
10.55k stars 4.22k forks source link

Docs: Interactivity API - Create a Core Concepts section for the iAPI #62921

Open juanmaguitar opened 5 months ago

juanmaguitar commented 5 months ago

Some core concepts related to the Interactivity API need a better explanation in the Docs. For that, I propose to create a section called "Core Concepts" with subpages covering some key concepts needed to understand how to work with the Interactivity API fully:

WPLake commented 5 months ago

It would be great if these pages included an introduction to the declarative approach, highlighting its benefits over the imperative one. Additionally, they should review the concepts independently, without mentioning any Gutenberg-related aspects.

This is necessary because WordPress has historically been heavily related to PHP, and many experienced, old-school WP developers may not have any reactive background at all, nor be aware of the Gutenberg block creation process.

iAPI aims to be a new standard for the WordPress front end, which is great. But to achieve this goal, we need to 'sell' it to the developers and avoid complicating the understanding of this new concept by mentioning unnecessary details.

I also propose covering the following essential points:

1. Declarative vs. Imperative approaches: Overview and explanation

Show a visual example highlighting the drawbacks of the imperative approach, then explain and promote the declarative one.

2. Interactivity vs. Reactivity: Explanation

Explain why the term 'interactivity' was chosen, and clarify its relation to and difference from the term 'reactivity.'

3. Why iAPI, and its benefits over alternatives (within WP)

The current About the Interactivity API page can be used as a base but should be made more presentable.

iAPI is a new concept, and most clients, as well as developers from other frameworks, are not familiar with it. Creating a strong presentation page that clearly shows the benefits and compares iAPI with other solutions (React/Vue/Alpine), even in a basic way, would be useful for sharing purposes.

It's necessary if we want to propose the iAPI as a headless alternative solution (at least for some cases). Currently, if you mention 'your front end will employ iAPI,' most colleagues/clients ask what it is, and there is no presentation link to send them. A good presentation page would help them:

a) Understand the overall idea b) Feel confident that such a front end is reactive, efficient, and modern.

Otherwise, iAPI usage will be refused in favor of a headless or a third-party solution. Additionally, many non-WP agencies and freelancers who use other tools but periodically take on WP-related projects would also benefit from such a 'promo & definition page.' Without it, they may never consider using iAPI even in the perfect use cases.

P.S. You can check this article we made at WPLake to see how we approached it. You might find inspiration or even reusable parts there.

juanmaguitar commented 5 months ago

Thanks @WPLake for the feedback!

I also propose covering the following essential points:

  1. Declarative vs. Imperative approaches: Overview and explanation ...
  2. Interactivity vs. Reactivity: Explanation

I agree these could be great topics to be covered in pages under "Core Concepts" section. Would you be up to write about them? If so, a good next step could be creating an individual issue for each one of these pages, describing the goal of the page and a raw outline of ideas to be covered in that docs page.

I think @luisherranz also wanted to start writing about some Core Concepts related to the iAPI in the docs, so having an issue for each piece of content would enable a proper conversation and organization around working on these topics to improve the iAPI docs.

WPLake commented 4 months ago

@juanmaguitar Glad to hear you like the suggestions. I've opened the issues, but they have the default label added automatically when choosing the issue type. I couldn't add the same labels as you did for this issue. I assume that's due to permission restrictions, but I hope it isn't a big deal to have the default [Enhancement] labels.

luisherranz commented 4 months ago

I have opened a pull request for the first guide:

luisherranz commented 4 months ago

I have opened another pull request for the second guide:

EDIT: In the end, I merged it with the first pull request, which includes the first three guides.

WPLake commented 3 months ago

@luisherranz Exciting news! I've read both, and they are great - well done! I'm sure with such documentation, iAPI will gain many more fans!

Currently, it's difficult to see the whole picture, but after publishing the new section, I assume we'll be able to have a general look and fill in if there are any gaps. The main thing is that the new foundation will be in place, making it easy to make minor improvements.

One more thing that could make the articles even more attractive is making examples playful, i.e., adding a live playground. Wouldn't it be great to wrap examples into JSFiddle or CodePen?

It seems new to wp.org, but if adopted, it could be useful in many places. I see a couple of ways:

  1. Store the snippets in a service like JSFiddle or CodePen and embed them.
  2. Wrap the existing snippets into an interactive element using the prefill-embed feature of CodePen, which allows the creation of playgrounds dynamically based on any code.

The second option looks attractive because you don't need to manage fiddles separately, but it requires injecting a script tag ('https://static.codepen.io/assets/embed/ei.js').

What are your thoughts on this?

WPLake commented 3 months ago

@juanmaguitar It seems the Core Concepts section is missing a 'How it works scheme overview,' which would explain the entire API's workflow based on a single page request. This could be useful for helping devs create and structure a general process roadmap, which other guides will then detail.

Not sure about the exact name, but we've made a pull request with the suggested content. Please review it and let us know your thoughts about the idea and if it needs any style polishing to meet the WordPress guidelines.

juanmaguitar commented 3 months ago

One more thing that could make the articles even more attractive is making examples playful, i.e., adding a live playground. Wouldn't it be great to wrap examples into JSFiddle or CodePen? Store the snippets in a service like JSFiddle or CodePen and embed them. Wrap the existing snippets into an interactive element using the prefill-embed feature of CodePen, which allows the creation of playgrounds dynamically based on any code. The second option looks attractive because you don't need to manage fiddles separately, but it requires injecting a script tag ('https://static.codepen.io/assets/embed/ei.js').

@WPLake, thanks for this suggestion! I agree that providing live examples of code snippets would be extremely helpful for understanding the documentation's explanations about the iAPI fully.

My approach here would be to add those snippets of code to block-development-examples and then show them in the code with WordPress Playground Block

This approach would allow:

Having said this, I'm curious about what an example would be of using CodePen or JSFiddle to display the outcome of some of the current examples in the docs. Do you have any example you could share?

WPLake commented 3 months ago

@juanmaguitar That's an amazing thing! We were unaware of this block; it truly seems impressive. We've previously had experience only with the WordPress playground for plugins (while setting it up for our Advanced Views plugin).

It definitely deserves to be highlighted on WordPress Playground Docs. We've raised an issue to include its mention.

Regarding the real example, I believe that all the mentioned full code examples can be integrated into the Playground. Our initial idea was to use CodePen/JSFiddle, which allows for third-party JavaScript (iAPI JS library), involving ready HTML while omitting server-side functions.

However, with the Playground block, it seems even more advantageous, as allows to play with the server side functions as well.

luisherranz commented 3 months ago

I have opened another separate pull request for the TypeScript guide. It is not finished yet, as I still need to document some use cases.

It should not be a blocker for merging the pull request of the first three guides.