Skip to content

Documentation: Rewrite Data docs as tutorial - #5379

Merged
aduth merged 7 commits into
masterfrom
update/data-docs-tutorial
Mar 7, 2018
Merged

aduth merged 7 commits into
masterfrom
update/data-docs-tutorial

Conversation

@aduth

@aduth aduth commented Mar 3, 2018

Copy link
Copy Markdown
Member

This pull request seeks to rewrite documentation for @wordpress/data to be less of a API overview and more of a walkthrough of expected uses of the module, explanations of key concepts, and contrasting with the Redux library upon which it is built. Importantly, it surfaces registerStore as the preferred registration point (introduced in #5206).

View Documentation

Testing instructions:

There are no code changes.

@aduth aduth added the [Type] Developer Documentation Documentation for developers label Mar 3, 2018
@youknowriad

youknowriad commented Mar 3, 2018 •

Copy link
Copy Markdown
Contributor

Haven't read yet, but maybe there's room for both. The README could stay more like an API reference and the tutorial could go in the handbook?

@aduth

aduth commented Mar 3, 2018

Copy link
Copy Markdown
Member Author

@youknowriad I tried to strike more of a balance, so the functions are all documented, just more elaboration of the "when", "why", and "how".

@youknowriad

Copy link
Copy Markdown
Contributor

@aduth Will take a deeper look.

As an aside, I think we should add a "modules" section to the handbook with the README of all modules. (A page per module)

@bordoni

bordoni commented Mar 4, 2018

Copy link
Copy Markdown
Member

Maybe the Comparison with Redux section could come right at the start after the description. Avoiding confusion to new people.

@youknowriad youknowriad left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Really nice work here 👍 I have a diverging opinion about the need to surface presentational/container components but it's fine

Comment thread data/README.md Outdated
- `store.subscribe( listener: Function )`: Registers a function called any time the value of state changes.
- _Redux parallel:_ [`subscribe`](https://redux.js.org/api-reference/store#subscribe(listener))
- Differences from Redux:
- In Redux, a subscriber is called on every dispatch, regardless of whether a change has occurred. In `@wordpress/data`, a subscriber is only called when state has changed.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not certain we have to mention this as it's a very small difference.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not certain we have to mention this as it's a very small difference.

Right. One of my initial goals in writing this was to highlight any and all differences to Redux, but I agree for most people this would have no impact. Do you think we should mention this anywhere? The "Comparison with Redux" section perhaps?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Moving to "comparison with redux" sounds good to me

Comment thread data/README.md Outdated
A higher-order component is a function which accepts a [component](https://github.com/WordPress/gutenberg/tree/master/element) and returns a new, enhanced component. A stateful user interface should respond to changes in the underlying state and updates its displayed element accordingly. WordPress uses higher-order components both as a means to separate the purely visual aspects of an interface from its data backing, and to ensure that the data is kept in-sync with the stores.

#### Example:
In the React/Redux ecosystem, this distinction is often labelled [_Presentational and Container Components_](https://medium.com/@dan_abramov/smart-and-dumb-components-7ca2f9a7c7d0). [React Redux](https://github.com/reactjs/react-redux) is the official bindings between React and Redux for providing this behavior. The higher-order components offered in the data module are very much like React Redux's `connect` function, but offered as independent functions for retrieving and manipulating data: `withSelect` and `withDispatch`.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I personally don't think it's necessary to explain Presentational and Container components, I feel it introduces more confusion than it solves.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I personally don't think it's necessary to explain Presentational and Container components, I feel it introduces more confusion than it solves.

What confusions do you have concerns about? I think the article goes into much more detail about this distinction and could be good for further reading, and to preempt thoughts of "Hey, that sounds a lot like...".

@youknowriad youknowriad Mar 5, 2018 •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know for a lot of people, this distinction is important but from mine, it doesn't make a lot of sense :).

A person reading this could assume that a Presentation component can be reused with any data or store, just providing props but that's not true because Presentation components can use Container components which means they are not reusable.

I like to think of everything as just React Components :). If I were to split types for React Components, I would prefer "Context-free components" and "Context-dependent components" :)

"Context-free" could be the UI components or the Presentation components

and

"Context-dependent" the more data heavy components

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the purposes of this document in introducing someone who may have no familiarity of these concepts, how can we set them on the correct course? Is a "presentational and container" distinction harmful? Or can it be seen as more of a guideline to encourage developers from tying their components too directly to a specific source of props?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So for me I think we can talk about connect as a Higher Order Component to inject props without the need to talk about Presentational and container components. Just explaining that a Higher Order Component is a function injecting extra props to a component and returning component.

I don't think you need to know Presentational and Container components to understand how HoC work.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, I think we could just remove it in the initial push.

One common pitfall I see where this distinction can be helpful is when component authors provide complex data unnecessarily to a component. Consider a <Title /> component where someone passes the post object and we render via the value of post.title. Why does that component need the entire post object? It doesn't; it's less reusable, and on a more practical level it causes issues with unnecessary re-renders via pure-render on the object (the value of the post object is likely to change more frequently than the title string). The component author should just pass in the title string.

Thinking that guides like this can be useful for helping avoid these pitfalls, even if the rules themselves shouldn't be so strictly binding.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree with the pitfall here, but not sure it's related to presentation/container separation, I know it's often explained when talking about this separation though.

I approved the PR, you choose :). I do have concerns about this separation but don't have strong objections to include it in the docs as it's a common React pattern people should know about.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm going to drop this paragraph. The previous paragraph has a brief mention of separating visual and data concerns, which I think is sufficient for now.

Comment thread data/README.md Outdated
To inject state-derived props into a WordPress Element Component, use the `withSelect` higher-order component:
#### `withDispatch( mapDispatchToProps: Function ): Function`

Use `withDispatch` to inject dispatching action props into your component. Passed a function which returns an object mapping prop names to action dispatchers, a higher-order component function is returned. The higher-order component can be used to enhance a presentational component, often providing callback behaviors for user interactions. The mapping function is passed the [`dispatch` function](#dispatch) and the props passed to the original component.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Technically withSelect and withDispatch can enhance any component and not only presentational components.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Technically withSelect and withDispatch can enhance any component and not only presentational components.

The thinking was to build upon this idea that visual components become enhanced to react to state with these higher-order components. Not to imply a sort of "rule" about when they can be used.

Do you have an example in mind that contradicts this advice?

@aduth

aduth commented Mar 5, 2018 •

Copy link
Copy Markdown
Member Author

Maybe the Comparison with Redux section could come right at the start after the description. Avoiding confusion to new people.

I'm a bit wary of this module being considered as merely "Redux for WordPress", for a few reasons:

  • Those using it may not have experience with Redux
  • We provide tools on-top of-, omit some features of-, and have behaviors diverging from Redux
  • To the above point, decisions about the direction of this module are considered in light of what makes most sense in WordPress, not strictly in how it aligns to Redux methodology

To me anyways, the most effective use of critical first sections of this documentation are in describing why and how it's to be used.

I would agree that for someone who happens to already be familiar with Redux, it's odd to not describe the comparison until the end of the documentation, particularly when there are multiple references to Redux documentation within the guide itself. Perhaps the introduction section could include a mention of this to make it explicit, with a link to the final section (similar to what existed previously with "exposes a Redux-like API").

@aduth
aduth merged commit f2bf8a1 into master Mar 7, 2018
@aduth
aduth deleted the update/data-docs-tutorial branch March 7, 2018 02:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Type] Developer Documentation Documentation for developers

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants