Documentation not newbie-friendly

[xelra]

Hi,

I'm trying to get started with Polymer and Redux, but even after days I don't really know how to get started. I'm trying to connect all the dots, but the documentation of this project is really confusing me.

The GitHub readme is so simple, I really can't make sense of it. When I go to the webpage of the project I see a demo app, but somehow it's only half of what the actual demo is and there are no explanations. Then in the docs there are these snippets of information and they all show different ways of how to do specific tasks and they're all different from how it's shown in the demo app.

It would really be great if there was a "Getting started" guide that would show a recommended way of setting up Polymer with Redux in a highly opinionated and idiomatic way, so that beginners could get started even before understanding all the concepts.

[tur-nr]

The readme is, it was intended to demonstrate the simplest way to achieve bindings to Redux. I mean there is not much more I can add to the readme to keep this easy.

• Create a store
• Create the Mixin
• Create your Element extending the Mixin
• Get some state

Are you confused with the Mixins, Redux or why you have a getState() method?

As for the website demo, it gets a little more specific. What I mean by this is actually connecting element properties to certain statePaths in the Redux store. Everything is still the same from the readme, only properties are getting defined on to the Polymer Element. If you have trouble understand properties in Polymer, I suggest reading the Polymer documentation. However, Polymer-Redux introduces a statePath key, this is called static binding.

Still, with the website demo, it is tabbed. These tabs are just representations of files that are split. Again if you have trouble understand how web components import code from various files I suggest reading more on this.

The documentation offers nothing too complex. All of which can be learnt outside of this library.

• Dynamic Bindings (Redux Reselect)
• Property/Action inheritance (Class Mixins)
• Action Creators is a way for you to define actions on your Element.
• Async Actions (Redux Thunk)

I mean I don't know what else or how I can write documentation to make this more understandable for developers. Please feel free to send a PR if my wording, grammar or if I've missed a link for you to follow and read.

As for a getting started guide for someone who doesn't know the concepts of anything relating to Polymer, Redux or Class Mixins. You may write one and please share. I'd be happy to include it in the readme or documentation. However, in my professional opinion, these are core concepts you need to know before using this library. It helps put the documentation into perspective.

[xelra]

Thank you very much for replying in this quite long comment. I know that from a perspective of someone who already knows this stuff, this might seem trivial. I, and probably many others that have come into contact with polymer-redux, do understand the basic concepts of all the parts involved. And in a few weeks from now, I probably can't understand what the fuss was about myself anymore.

But right now the UX is fresh in my mind, so I will try to elaborate the hardships I encountered.
I'm a hobbyist developer and somewhat learning JS, Polymer and Redux at the same time. After having finished my first basic Polymer app and connected it to an api, I realized, while implementing auth, that I needed some way of passing state between elements. After reading up on it I decided to do that centrally, because the complexity of managing state might grow fast, and came to Redux.

So I landed on your GitHub page and saw the demo app, then I clicked the polycast video. Here was the first time I got really confused. The syntax that Rob used was really different from what I saw from the demo app. After some investigating I found out that it's because that's Polymer 1 (I haven't done anything in P1, so I didn't know).
The first thing here that got me confused when comparing the video with the demo is

case 'UPDATE_MESSAGE': return {message: action.message};

vs

case 'ADD_FRIEND' :
	const friends = state.friends.slice(0);
	friends.push(action.freind);
	return Object.assign({}, state, { friends: friends });

I thought "OK, maybe that's a P1 vs P2 thing or maybe it has something to do with ES6", so I went on to the store.

const store = Redux.createStore(reducer);
const ReduxBehavior = PolymerRedux(store);

vs

const store = Redux.createStore(
    reducer,
    initial,

    // The best part 8)
    Redux.compose(
      window.devToolsExtension
        ? window.devToolsExtension()
        : v => v
    )
  );
  
  // Create the Polymer mixin
  ReduxMixin = PolymerRedux(store);

"Alright, that's so different". At this point I started googling, trying to bring in additional information, because I just couldn't figure it out. After some time I learned that the second part is just a Mixin which replaces the Behavior from P1. The creation of the store still leaves me with no understanding of the differences though, even after days. winow.devToolsExtension? What is v? Arrow function? w00t?

Then in the comments of the Polymer video I found someone changing it up for P2. "Let's check out the reducer and the store creation".

const store = Redux.createStore(
    reducer, /* preloadedState, */
    window.devToolsExtension && window.devToolsExtension()
);

More confusion. No v, still the window.devToolsExtension that I don't understand. No ternary operator, instead just both go to the store. Why?

Then I went back to the demo app on the polymer-redux webpage. In the reducer there's the UPDATE_MESSAGE action, but where does it come from? Where is it dispatched?
When clicking the "Demo" tab, suddenly there's an input field. "Ah yes, there it is. But where's the code? Let's check out the GitHub page and also really carefully read the docs section again".

connectedCallback() {
        super.connectedCallback();
        const state = this.getState();
}

"What?" It's another thing that is neither in the demo app nor in the video or in the P2 code of the video.
"It probably has something to do with actions. Let's check the docs"

connectedCallback() {
    super.connectedCallback();

    // Let's update the message
    this.dispatch({
      type: 'UPDATE_MESSAGE',
      message: 'This is MAGIC!',
    });
  }

"This is different again. Magic indeed! Well, maybe I'm just an idiot."

And then I wrote this post after multiple days of trying to make sense of the docs.
Most of these things are probably trivial for a seasoned developer, but this multitude of different methods to achieve the same thing is just so hard to make sense of for a beginner.

Oh yes, one more thing. In the P1 video the redux.js is explicitly loaded in the index.html. In the demo app it isn't though. Is it implicitly loaded in the P2 version of polymer-redux?

[timeu]

I really think that one has to first learn Redux and all the concepts around it.
I highly recommend to watch Dan's Redux Videos (Dan is the creator of Redux) https://egghead.io/courses/getting-started-with-redux

Polymer-redux is just a thin wrapper that allows you to connect the Polymer elements to the redux store similar to React-Redux bindings (https://github.com/reactjs/react-redux)