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

[juanmaguitar]

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:

• Core Concepts - to start with, some inner pages coveting core concepts could be ...
  • Reactivity - don’t mutate DOM.
    • iAPI Docs: The Reactive and Declarative Mindset #63759
  • Global state, local context, and derived state
    • iAPI Docs: Understanding global state, local context and derived state #63930
  • Server directive processing - initial state
  • Client-side navigation
  • Scope
  • Namespaces
  • Script modules

[WPLake]

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]

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]

@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]

I have opened a pull request for the first guide:

• iAPI Docs: The Reactive and Declarative Mindset #63759

[luisherranz]

I have opened another pull request for the second guide:

• iAPI Docs: Understanding global state, local context and derived state #63930