[Draft] Data layer overview #37615

adamziel · 2021-12-23T14:26:52Z

This is a first draft of a Gutenberg data layer overview. I hope it will help new contributors get up to speed faster. As a follow-up, I would prepare an actual tutorial on building a small app using the material covered here.

There's still a lot I want to change, but I'm posting it here for early feedback anyway. It's easier to improve now than it will be later.

cc @youknowriad @jsnajdr @noisysocks @talldan @draganescu @ntsekouras @jorgefilipecosta @ellatrix @kevin940726 @tellthemachines @priethor @mtias

adamziel · 2021-12-23T14:56:08Z

A comment I found in my notes:

What’s the data flow when we call getEntityRecords and other similar APIs? How is the data stored? When will the data invalidate? How to do error handling / pagination / batch requests?

youknowriad · 2021-12-27T09:18:05Z

I guess the most important thing for me first, is to figure out where this fits and how it aligns with the existing data related docs. Is this a README of the data module? Is this an "architecture" doc to put under the architecture section? Is it specific to core-data? Should we split it?

I want to avoid the effect of just adding docs that duplicate some existing docs, and adds good additions... but at the same time confuses the reader. I guess I'm just saying we should think about organization and consolidate with existing documentation.

mkaz · 2021-12-27T15:26:25Z

I echo @youknowriad's comment - we should try to find a good spot and think how it fits with the rest. My sense with the way it is now would be the explanations/architecture section.

The Gutenberg documentation is structured based on this documentation system with the main sections being:

Getting Started - going from zero to an initial basic piece (block, pattern, block theme). I don't quite think it fits here because it is a more advanced topic
How to guides - these are specific tasks that a developer is trying to accomplish, and the primary focus of the documentation is to complete the task, not necessarily around learning concepts
Reference guides - these are technical API docs, here are the functions and how they work. Some of the documentation you have can enhance these docs around core-data.
Explanations - these are longer documents explaining concepts and ideas, this fills like the right fit for most of this document.

getdave · 2022-01-06T17:00:49Z

One thing I will add here - I believe this documentation is critical and I applaud all the effort that has clearly gone into this. We get a lot of questions from contributors (even those who are otherwise well versed in the project!) on the data layer.

I agree we should decide where this fits. I'm going to give it a read and leave some thoughts.

getdave

I got this far a review. I'll tackle the rest tomorrow or early next week.

docs/getting-started/data.md

getdave · 2022-01-06T17:15:53Z

docs/getting-started/data.md

+null
+```
+
+First, `getTemperatureCelcius` does not refer to the same function as we originally registered with the store (`( state ) => state.temperature`). Instead, the `data` package replaced it with a „resolved” version using the [mapResolvers](https://github.com/WordPress/gutenberg/blob/5dbf7ca8a285f5cab65ebf7ab87dafeb6118b6aa/packages/data/src/redux-store/index.js#L366-L442) utility. The function we’re actually calling is [`selectorResolver`](https://github.com/WordPress/gutenberg/blob/5dbf7ca8a285f5cab65ebf7ab87dafeb6118b6aa/packages/data/src/redux-store/index.js#L388) . It does two things:


...the same function as we originally registered

Are we referring to the selector or the resolver here?

tellthemachines

Thanks for writing this up Adam! I agree that more info on how our data packages work is needed to help guide contributors. I'm also not clear on where this should live, but here are some thoughts:

As this stands, it reads to me more like a blog post than a technical doc (especially the sections on entity records). Publishing it as a series of blog posts is definitely a possibility! With the data package at least we're covering similar ground to @nerrad 's series on the subject, but it's great to have multiple takes on the same topic, because different people will find one or the other easier to understand.
It would be nice to have some docs covering the architecture of these packages in the packages themselves, for the benefit of potential contributors. Having the docs live close to the code has the advantage that searching for a keyword (e.g. a function name) in the project will bring up the doc, which might be helpful.
If we want this to be an architectural doc, it should be as short and to the point as possible, to make it easy to browse through and find the needed info (because we all know devs love to read long docs, right? 😅 ) so we'd need to do some editing work here. In this case we should also build as much as possible on the existing docs, improving them where needed and linking to them instead of duplicating effort.

Hope this helps!

docs/getting-started/data.md

tellthemachines · 2022-01-07T02:32:31Z

docs/getting-started/data.md

+The `@@INIT` action is dispatched when the store is instantiated, and so the initial state says `temperature: 0`
+
+### Simple selectors
+The  `getTemperatureFarenheit` is a simple selector, it predictably returns `0` once the store was instantiated:


Not sure I understand this example. The selector structure led me to assume the temperature was stored in Celsius. If the initial temperature is 0, won't that be 32 in Farenheit?

We already have a decent overview of how selectors etc. work here so perhaps we should just reference that example?

tellthemachines · 2022-01-07T02:40:43Z

docs/getting-started/data.md

+}
+```
+
+It is a [thunk](thunks%20link) that populates the state. Note  that it does not return anything, nor there are any assumptions on how the data is loaded. The sole goal of this function is to populate the state, and it does so by dispatching the `receiveTemperature` action when the data is ready.


...nor are there any assumptions...

docs/getting-started/data.md

tellthemachines · 2022-01-07T03:22:25Z

docs/getting-started/data.md

+
+## Entities
+
+Entities are like data types. A Post is an entity, so is a Taxonomy and a Widget. We will use the latter as our running example. Default entities are declared in `entities.js`, and a minimal definition looks like this:


"Entities are like data types" sounds a little vague. How else can we define them? Something like "objects" or "types of content" maybe?

Because each entity corresponds to a REST API endpoint, might it be helpful to add that entities are equivalent to REST API "resources"?

I like the REST metaphor! How about something like below? I used three different examples to have a better chance of shoehorning this on top of some prior knowledge the reader has.

An entity is a basic unit of information in core-data. Entities are conceptually similar to REST API resources, database entries, and class objects. A Post is an entity, so is a Taxonomy and a Widget.

docs/getting-started/data.md

Co-authored-by: Dave Smith <getdavemail@gmail.com>

adamziel · 2022-01-18T15:29:09Z

Thank you so much for your reviews @tellthemachines and @getdave, it's extremely helpful!

As I was editing, I noticed I have two competing priorities here:

New developers who aren't sure how to work with Gutenberg data APIs
Gutenberg contributors and advanced developers who need complete mental models of the two modules

I am thinking about splitting this into two separate docs:

A lightweight Askeet-style guided tour that shows how to use the software. Gutenberg data 101?
A deep dive into the internals, data flows, and redux state transitions. Gutenberg data 202?

I'm curious about your thoughts @youknowriad @mkaz @draganescu @getdave @tellthemachines

First draft

7fae734

adamziel added [Type] Developer Documentation Documentation for developers [Package] Data /packages/data [Package] Core data /packages/core-data labels Dec 23, 2021

adamziel self-assigned this Dec 23, 2021

adamziel requested review from ajitbohra and mkaz as code owners December 23, 2021 14:26

getdave reviewed Jan 6, 2022

View reviewed changes

tellthemachines reviewed Jan 7, 2022

View reviewed changes

draganescu reviewed Jan 17, 2022

View reviewed changes

docs/getting-started/data.md Outdated Show resolved Hide resolved

adamziel and others added 15 commits January 18, 2022 13:49

Update docs/getting-started/data.md

5fcbcef

Co-authored-by: Dave Smith <getdavemail@gmail.com>

Update docs/getting-started/data.md

688625f

Co-authored-by: Dave Smith <getdavemail@gmail.com>

Update docs/getting-started/data.md

be94e07

Co-authored-by: Dave Smith <getdavemail@gmail.com>

Update docs/getting-started/data.md

9a1b9ff

Co-authored-by: Dave Smith <getdavemail@gmail.com>

Update docs/getting-started/data.md

bb542d6

Co-authored-by: Dave Smith <getdavemail@gmail.com>

Update docs/getting-started/data.md

6f687f3

Co-authored-by: Dave Smith <getdavemail@gmail.com>

Update docs/getting-started/data.md

3481cee

Co-authored-by: Dave Smith <getdavemail@gmail.com>

Update docs/getting-started/data.md

070e2dc

Co-authored-by: Dave Smith <getdavemail@gmail.com>

Fix typos and rephrase unclear sentences

b0f1f11

Expand on what an entity is

00d7c44

Expand on what an entity is

8e3bb64

Fix typos and inconsistencies

cb67c47

Update docs/getting-started/data.md

fdcf44f

Co-authored-by: Dave Smith <getdavemail@gmail.com>

Focus on getEntityRecords() usage rather than implementation

b0acc96

Focus more on the getEntityRecords usage and less on the implementation

bd06705

This was referenced Jan 21, 2022

Entity records hooks #38135

Closed

Tutorial: Create your First App with Gutenberg Data #38250

Merged

adamziel mentioned this pull request Feb 4, 2022

useEntityRecord (experimental) #38522

Merged

skorasaurus mentioned this pull request May 25, 2022

Documentation: Document usage of core entities (getEntityRecords, etc) #12120

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Draft] Data layer overview #37615

[Draft] Data layer overview #37615

adamziel commented Dec 23, 2021

adamziel commented Dec 23, 2021

youknowriad commented Dec 27, 2021

mkaz commented Dec 27, 2021

getdave commented Jan 6, 2022

getdave left a comment

getdave Jan 6, 2022

tellthemachines left a comment

tellthemachines Jan 7, 2022

tellthemachines Jan 7, 2022

tellthemachines Jan 7, 2022

adamziel Jan 18, 2022 •

edited

Loading

adamziel commented Jan 18, 2022 •

edited

Loading


		## Entities

		Entities are like data types. A Post is an entity, so is a Taxonomy and a Widget. We will use the latter as our running example. Default entities are declared in `entities.js`, and a minimal definition looks like this:

[Draft] Data layer overview #37615

Are you sure you want to change the base?

[Draft] Data layer overview #37615

Conversation

adamziel commented Dec 23, 2021

adamziel commented Dec 23, 2021

youknowriad commented Dec 27, 2021

mkaz commented Dec 27, 2021

getdave commented Jan 6, 2022

getdave left a comment

Choose a reason for hiding this comment

getdave Jan 6, 2022

Choose a reason for hiding this comment

tellthemachines left a comment

Choose a reason for hiding this comment

tellthemachines Jan 7, 2022

Choose a reason for hiding this comment

tellthemachines Jan 7, 2022

Choose a reason for hiding this comment

tellthemachines Jan 7, 2022

Choose a reason for hiding this comment

adamziel Jan 18, 2022 • edited Loading

Choose a reason for hiding this comment

adamziel commented Jan 18, 2022 • edited Loading

adamziel Jan 18, 2022 •

edited

Loading

adamziel commented Jan 18, 2022 •

edited

Loading