Giters

keajs / kea-docs

Home Page:https://kea.js.org/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

"Things I found confusing while reading the docs"

timgl opened this issue · comments

commented
  • "Actions themselves are simple and pure functions. The only thing they are allowed to do is to convert their arguments into a payload object." I don't understand why I need to return this as a dict which calls itself. What happens with that dict later on? Because when I write reducers I then need to take it from an object again. I did have a bug with this while using the loaders plugin before.
  • On the selectors bit, I don't really understand why I can't create a reducer that's made up of 2 other reducers. In my mind, reducers are the things that end up as values so if I want something that I can use as a value, I use a reducer. I'm sure there is a good reason for this.
  • Layout wise, especially in advanced concepts It would be nice to have some kind of separation (a line) between the different sections as I end up skimming and the distinction between h2 and h3 isn't big enough for me to understand that it's a different section.
  • Props weren't explained in the core concepts, but we do use them quite a lot so I think they are important?

These are slightly nit-picky. I think these docs are a huge improvement over the old ones, and a lot of concepts are now much clearer!

commented

Maybe we can make the Quickstart be a top level topic before the Guide and it can have an intro in a sense and move the current note to the bottom about why you should also read the Core concepts.

Intro

Kea consists of these elements 1, 2, 3.

Content

And this is how you use them. (current content)

The docs are a HUGE improvement in explaining what Kea does and how I should be using it. There are concepts here I did not know I was supposed to use 👍

commented

Hi @timgl and @madisvain , thanks for the feedback!

Tim, regarding your points:

  • It's indeed true that you don't really have to convert the action arguments into objects for payload... but I've found that it really helps if every payload is an object. Otherwise you'll have about 50% of your payloads be objects like { id, name } and the other 50% just scalars id. It'll be especially confusing, if you have one reducer (e.g. todos) and for some actions (removeTodo) the payload is just id, but for others (editTodo) it's { id, todo }. I've found that keeping to a convention where payloads are always objects removes one thing you need to think about and makes for cleaner code. "Was it an object or was it a just an id? I'd better check to make sure I don't make a mistake.". I could be off here and I'm willing to reconsider this stance.

  • I'm not I understand what you mean with "why I can't create a reducer that's made up of 2 other reducers.". You can have a selector that is made up of two or more selectors... and each reducer gets a selector automatically. Selectors are basically just "computed values", a pattern I've seen in many reactive programs and frameworks, from excel to ember-data. Perhaps it's just badly explained.

  • Agreed, the "advanced concepts" section itself is a sort of hotchpotch of random topics and could be structured better. Some lines could help, I need to think of this.

  • It might indeed make sense to move props (and keyed logic?) to core concepts. They are quite core indeed. However I feel that this core page has already gotten too long as it is...?

Madis, for your comment:

  • It's an interesting idea and worth looking into. Would you integrate the "installation" there as well? I'd personally prefer it though if people would skip the quickstart and read the "core concepts" to get a better understanding of the topics. If you read the quickstart fully, it's easy to start skipping sections in "core concepts" as a lot of the text is the same. But I get that you might just want to see how kea looks like without investing a lot of time in reading about it. I don't know :D.
commented
  1. I don't actually mind what I have to do and it seems very sensible to me, my point was more around the fact I didn't understand how those names get passed around. I think just adding the explanation you just gave would already help towards making me understand 👍
  2. Again I think the actual pattern does make sense, I guess I still don't entirely understand the difference between reducers and selectors. I think what might help is having a super simple diagram that just explains how data flows through Kea? from action -> reducer -> selector -> events etc.
  3. :)
  4. Agree core page is long and now I'm writing Kea props do feel fairly natural, though I might still be using them wrong at the moment.
commented

@mariusandra Having the note before makes a fair point.

Installation step seems to part of most of Quickstarts that I have looked into.

The introduction I'm missing is:

The itroduction could maybe explain a bit What kea is and what problem is it trying to solve?

A little thing to also consider is that the Quickstart code does not make sense if you try to combine it into a CodeSandbox - I tried to do. So if you are a person who needs to follow along and see the parts working together then the Quickstart can be a bit confusing.

These are just my ideas about proposed improvements :)

commented

@timgl regarding reducers and selectors, they are different things. Perhaps this explanation clarifies it a bit?

Reducers store data in redux:

var state = {  // `a` and `b` are updated via reducers
  a: 123, 
  b: 345 
};

Selectors get data from redux:

const aSelector = state => state.a
const bSelector = state => state.b
console.log(aSelector(state))

You can make new selectors that have other selectors as input:

const newSelector = state => aSelector(state) + bSelector(state);
console.log(newSelector(state))

Kea via reselect adds the feature that newSelector will be cached and will only be recalculated if either the return value of aSelector(state) or bSelector(state) changes and not before.

Agreed though that a diagram to explain all of this can be valuable.

commented

@madisvain what you're saying makes sense.
Here's another one: https://react-redux.js.org/introduction/quick-start