Coordinating our documentation efforts

[AlphaZebra]

EDIT: You can now go to the Documentation Tracking Issue to see the status of this work

---

Hi, I'm creating this thread as a place to exchange information about work we're doing around documenting the Interactivity API. That would include things like not duplicating effort, discussing how best to present key concepts, and so on.

As I write this, I'm by no means fully conversant with the Interactivity API, but I'm hoping to turn this to an advantage in that I can write from the point of view of someone who just answered (or was helped with an answer) by themselves.

By way of starting off, I'm wondering whether there needs to be some discussion (not sure where) about makes a modern declarative framework different from the traditional PHP backend of WordPress. It's true that almost all of this is built into Mario Santos's great API Proposal writeup, but it's written more toward an audience that already has some experience with something like React, someone who's developed dynamically rendered blocks, and someone who has at least an inkling what a "PHP directive" is, or what hydration is.

I may be wrong that there's a need for this (maybe directing someone to an overview of React or Preact would suffice?), but for the moment I plan to take a stab at this "So you want to figure out what the Interactivity API is all about..." document in the next few days and then hope to get feedback about what works and doesn't.

And I'd encourage anyone else who's working on documentation to use this thread as a coordination point!

[luisherranz]

Thanks, Robert!

maybe directing someone to an overview of React or Preact would suffice?

To be honest, I don't know either.

In the WCEU workshop, I tried to compare it with React because I think for those who know React, it's quicker to make the mental connection when you understand that the Interactivity API is like using React but with a different syntax, instead of something entirely new.

But for those who don't know React, it is something entirely new 🤷‍♂️

Maybe we can focus the documentation on those who don't know React, but add details for those who do know React.

What do you think, @juanmaguitar?

[juanmaguitar]

Maybe we can focus the documentation on those who don't know React, but add details for those who do know React.

AFAIK in order to use the Interactivity API you don't really need to know React, so I think most of the documentation for the Interactivity API could assume readers don't know (or have to know) React.

For some deeper explanations about the "engine" behind the Interactivity API or the advantages of using the Interactivity API vs other approaches, more advanced knowledge may be expected and clear references to (or comparisons with) React could help the average developer to understand better some of these topics.

I think using details or similar UIs could be a great way to add these extra explanations/references specifically targeted to React developers (whenever necessary).

[luisherranz]

AFAIK in order to use the Interactivity API you don't really need to know React

This statement is true. But it's also true that in order to create a fully working block, you do need to use React for the Edit component. So it's a bit trickier.

Anyway, I'm happy you like the idea of the extra details for React developers. We can try that, see how it feels 🙂

[AlphaZebra]

Good points... My point was, now that I think about it, perhaps more generically about how components are things that render themselves on an as-needed basis. If you've strictly stuck to WordPress PHP, you won't have encountered anything like it. Conceptually, it's not really that complicated, but the new terminology and approach make it sound pretty mysterious, so maybe it makes sense to just de-mystify some key points. Details may be the way to do this--as @luisherranz says, we can see what we want to say and then see how it fits in if we go that route.

[luisherranz]

There's also another point about the React connection: you are using React (well, Preact) so sometimes, you'll want to implement patterns that use (P)React tools because they are composable and powerful.

For example, maybe sometimes you'll want to do something like this in your Interactivity API code:

import { store } from "@wordpress/interactivity";
import useInView from "some-use-in-view-react-hook-library";

store({
  effects: {
    someEffect: ({ ref }) => {
      const isInView = useInView(ref);

      useEffect(() => {
        if (isInView) {
          // Do something here when the component is in the viewport.
        } else {
          // Do something here when the component is not in the viewport.
        }
      }, [isInView]);
    },
  },
});

Sure, it may be possible to provide tools to somehow hide the fact that you're running a Preact app, and do this instead:

import { store } from "@wordpress/interactivity";
import isInView from "@wordpress/interactivity/utils/is-in-view";

store({
  effects: {
    someEffect: ({ ref }) => {
      if (isInView(ref)) {
        // Do something here when the component is in the viewport.
      } else {
        // Do something here when the component is not in the viewport.
      }
    },
  },
});

Full working example

But why reinvent the wheel? It was never the goal of this API to create a fully-fledged framework capable of replacing (P)React, but to provide a version of (P)React that works in PHP and has compatibility with how WordPress works. If this is somewhat true: Should we really say that knowledge of (P)React is not required? And how much knowledge of (P)React is required to get started?

[dgwyer]

As a newcomer to the Interactivity API, wanting to learn more, I'd find it useful to have a 'Getting Started' guide in place so people can start playing with it, and a list of use cases to generate interest and engagement. The movies app is great but I think a wider set of use cases would be beneficial to start to understand the full potential of this new API.

I'm still only just diffing into it right now but if I can help with the getting started guide or any other docs then I'd be happy to help.

[mtias]

+1 to having more examples and use cases!

[Ren2049]

I think follow along tutorials for useful functionality not part of the core blocks but still within a blogging context could be great, for example an exit intent modal or a sticky table of content sidebar that updates the highlighted chapter based on the heading in view.

This is stuff people want because it has business value and would be used right away. I think there's a lot of inspiration for types of interactive components within third party block libraries with interactive blocks. Performance minded users (early block editor adopters for example) are most likely interested in replacing a lot of those JQuery components that are still within a lot of block plugin libraries.

YT is a a good resource to learn React or whatever, I wouldn't reinvent the wheel and try to teach React or Preact if you're not cut for teaching. Most likely there's already a better resource on YT for free. I think React is declarative/explicit enough to get the hang of it if folks follow along and build a bunch of things with it.

I think having some components or functionality that people want or need for their day to day is more important. People will figure out the rest with some links to some good resources.

I've learned JS and React back in 2017 out of curiosity about Zeit and NextJS, but went into the design, nocode and small business direction instead and forgot almost everything except HTML and CSS (and very basic JS) because I just didn't need it and therefore wasn't able to build a regular coding routine.

But something like the interactivity API and interactive block plugins that would enhance my own block theme development could reignite my interest in coding and React.

[luisherranz]

Another important concept to teach is that people should never update the HTML manually. They should use always directives, and then mutate the state if they want to change the HTML.

The Interactivity API follows the same principle as React: UI(state) = HTML. The HTML is never modified manually. Instead, it is derived from the current state, which is processed by the UI logic to produce the HTML. When you want to modify the HTML, you mutate the state, not the HTML: UI(newState) = (new) HTML.

I thought this was going to be obvious, but apparently is not. Yesterday I saw a person using ref.classList.add, ref.textContent and ref.addEventListener inside a selector referenced by a data-wp-text directive. We need examples to make sure people understand that that is an antipattern and it will lead to bugs, complexity and things not working as expected.

Of course, there are always exceptions to the rules, but those are minimal and should only be used when using directives + state is not possible (i.e., toggling a class of the body tag, because you can't add a directive to the body tag from your render.php file).

[luisherranz]

Hey folks, if you still want to help with the documentation, things are about to get in motion 🙂

First, @juanmaguitar is going to lead the documentation efforts and design the documentation structure.

Second, he will open a new Tracking Issue that we can use to coordinate, divide tasks, know who's working on what, what needs to be reviewed and so on.

And third: apart from that, he'll work on a Make Core post to share the progress of the Interactivity API proposal. It will likely include:

• The current status of the Interactivity API (available from GB 16.2)
• Where to ask questions or have conversations about it
• From where the progress of the project can be followed
• What are the plans for the next months
• Where to learn about how to use it
• Some guidance to help with the docs (Tracking Issue, related discussions...)

[luisherranz]

This issue will introduce a bare-bones version of the docs, so we have some basic structure to work on: #52922

[AlphaZebra]

I've been truly buried the past few weeks and will probably remain pretty deep in through the WCUS, and as a result, I haven't really dug into doing anything hands on with the API, but I definitely want to get going with this, so I guess I better carve out some time and get a test installation going. I do suspect that the stupid questions I'll be coming up with can be recycled into useful bits and pieces of the documentation. Anyway, just registering that I'm still on board, just not being very useful as yet.

[AlphaZebra]

Not sure where to ask this, but is anyone planning to talk about the Interactivity API at the Rochester Wordcamp at the end of September? If not, I was thinking I'd propose a talk. Obviously, I don't have the insider technical depth, but I have a very good understanding of what motivates the project. I was thinking of something partly talking about what you might want it for (fairly high level) and, at a fairly high level, how it's technically structured. Love to do it, but don't want to accidentally get in the way of someone who actually knows what they're talking about... ;-)

[luisherranz]

Not that I know of. I think @ryanwelcher was also thinking about proposing a talk for a conference, but I'm not sure which one.

So if you want to propose a talk, please do. And if you need help just let me know. Also, preparing a talk is a great way to get immersed in a topic 🙂

[ryanwelcher]

I have proposed a talk for WC Omaha and am planning to submit to WC Asia as well. Great to see that you're planning to submit @AlphaZebra and if you need any support, I'm happy to help.

[luisherranz]

There's now an initial version of the documentation of the API 🎉 🎉

• Interactivity API: API Reference

Feel free to open pull requests to improve any part of it, or even add other sections or files to the docs.

---

@juanmaguitar also opened Tracking Issue to ease the coordination of the work:

• Documentation for the Interactivity API - Tracking Issue #53296