DataViews documentation: add high-level graph explaining DataViews and data sources interaction

[oandregal]

What?

Adds a graph to the DataView's README explaining how DataViews works with data sources.

DataViews is data agnostic, it can work with data coming from a static (JSON file) or dynamic source (HTTP Request) — it just requires the data to be an array of objects that have a unique identifier. Consumers are responsible to query the data source appropriately based on the DataViews props:

Why?

Through conversations, one consistent struggle people had was "how DataViews work with data?". People either assumes that DataViews is responsible to fetching data from an endpoint or that it can only work with static data. Far from the truth, DataViews can work with data coming from anywhere and it's important to clarify this.

How?

Expands the intro to DataViews component in the README and adds a graph explaining the data flow.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: oandregal <oandregal@git.wordpress.org>
Co-authored-by: youknowriad <youknowriad@git.wordpress.org>
Co-authored-by: juanmaguitar <juanmaguitar@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[oandregal]

I'm not sure this is the right way to embed images in the handbook. Do they still need to be in a external source (for example, pointing to the image as stored in this GitHub PR)?

[oandregal]

Also, I'm more than happy to collaborate and improve that graph: it's something I just created with the tools I had but other people may be able to create a better one.

[youknowriad]

For the existing image we have in the handbook, we use the full URL https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/explanations/architecture/assets/modules.png. Not sure why or if it's better though.

Also, we do keep the "source" modules.excalidraw file in the repo to be able to edit it in the future if needed.

[oandregal]

Also, we do keep the "source" modules.excalidraw file in the repo to be able to edit it in the future if needed.

I can explore redoing the graph using excalidraw. Happy if anyone else beats me to it (have a bit of an hectic week).

[youknowriad]

No need to redo it if you lost your source or did it with some other tool, it was just a suggestion based on what I did before :)

[oandregal]

I just used Obsidian Canvas and I have the source file that I can share. I'm just not sure how useful it'd be to anyone else? 😅 It seems excalidraw would be a more widely known format/app, and I agree having a source file to re-generate the image from is very useful.

[juanmaguitar]

The best way to use images in the Handbook is to upload them to the Media Library for the Handbook's WordPress installation and reference it from that URL (see example)

Happy to help in uploading the required images to the Handbook's WP installation.

There are several excalidraw diagrams in the Block Editor docs. The original diagram link (where things can be modified) can be added to a Resources list at the end of the page, but that's not always needed (I don't think it's needed in this case)

Note: For accesibility issues the link to the image containing the diagram should also point to an image

[juanmaguitar]

I added the image to the https://developer.wordpress.org/files so it can be referenced from there
https://developer.wordpress.org/files/2024/09/368600071-20aa078f-7c3d-406d-8dd0-8b764addd22a.png

[juanmaguitar]

@oandregal if you change the link of the image to point to the URL above I think we can move forward with this PR.
I'm approving it to unlock the merge.

[oandregal]

ok, pushed those changes (be welcome to push them yourself in the future!). In the interest of shipping small improvements regularly, I'm merging this one. Perhaps we need to revisit it to also include DataForm documentation here. At that point, I can try with excalidraw.