New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs improvements #140

Closed
wants to merge 42 commits into
base: master
from

Conversation

@acdlite
Collaborator

acdlite commented Jun 18, 2015

PR to keep track of docs improvements, as discussed in #137

  • Rename Stores to Reducers
  • Rename the “Redux instance” to Store as per #137 (comment)
  • Explain that if you squint at traditional Flux Stores, you'll see Reducers trapped in them
  • Glossary of terms
  • JSDoc (and/or Flow annotations)
  • Design decisions
  • Updated README (with focus on familiar Flux concepts; keep advanced stuff in docs)
  • "Getting Started" guide
  • Explanation of how to subscribe to changes manually, without Provider and Connector #134 (comment)
  • Higher-order stores (possibly call these "store transformers"?)
  • Full API docs
  • Touch on sugar like createReducer, createActionCreators haha
  • Anti patterns (e.g. #291)

Focus right now is to get these items completed in Markdown form. Then (or in parallel) we will turn these into a proper docs site.

@acdlite acdlite added the docs label Jun 18, 2015

@emmenko

This comment has been minimized.

Show comment
Hide comment
@emmenko

emmenko Jun 18, 2015

Collaborator

👍

Collaborator

emmenko commented Jun 18, 2015

👍

@emmenko

This comment has been minimized.

Show comment
Hide comment
@emmenko

emmenko Jun 18, 2015

Collaborator
Collaborator

emmenko commented on 22f377b Jun 18, 2015

@acdlite

This comment has been minimized.

Show comment
Hide comment
@acdlite

acdlite Jun 20, 2015

Collaborator

This my weekend project. I started working on a new version of the README. I think that target audience for the README is developers who aren't super familiar with functional programming, and are skeptical of yet another Flux library. So, the focus should be on explaining how Redux significantly improves on the traditional Flux architecture, but is still very familiar.

I'm going to move most of the current README into separate documents and link to them from the table of contents. The rough outline will be

I. Key features (like an elevator pitch) (includes links, so also like a summarized table of contents)
2. Why Redux? (slightly longer elevator pitch)
3. Code sample
4. Link to tutorial
5. Link to example apps
6. Index for rest of docs

The reason the index goes at the end is because the current table of contents, while good, could be overwhelming for new visitors. The initial impression should be "hey, Redux is very simple and easy to learn."

Collaborator

acdlite commented Jun 20, 2015

This my weekend project. I started working on a new version of the README. I think that target audience for the README is developers who aren't super familiar with functional programming, and are skeptical of yet another Flux library. So, the focus should be on explaining how Redux significantly improves on the traditional Flux architecture, but is still very familiar.

I'm going to move most of the current README into separate documents and link to them from the table of contents. The rough outline will be

I. Key features (like an elevator pitch) (includes links, so also like a summarized table of contents)
2. Why Redux? (slightly longer elevator pitch)
3. Code sample
4. Link to tutorial
5. Link to example apps
6. Index for rest of docs

The reason the index goes at the end is because the current table of contents, while good, could be overwhelming for new visitors. The initial impression should be "hey, Redux is very simple and easy to learn."

@gaearon

This comment has been minimized.

Show comment
Hide comment
@gaearon

gaearon Jun 20, 2015

Collaborator

I think that target audience for the README is developers who aren't super familiar with functional programming, and are skeptical of yet another Flux library. So, the focus should be on explaining how Redux significantly improves on the traditional Flux architecture, but is still very familiar.

Yes!

Collaborator

gaearon commented Jun 20, 2015

I think that target audience for the README is developers who aren't super familiar with functional programming, and are skeptical of yet another Flux library. So, the focus should be on explaining how Redux significantly improves on the traditional Flux architecture, but is still very familiar.

Yes!

@gaearon

This comment has been minimized.

Show comment
Hide comment
@gaearon

gaearon Jun 21, 2015

Collaborator

Idea for fans of cursors: showing how to implement a cursor-like functionality with Redux using a single reducer and a single SET action. Use case: you like cursors but want benefits of Redux (time travel etc). Also because it's a fun experiment.

Collaborator

gaearon commented Jun 21, 2015

Idea for fans of cursors: showing how to implement a cursor-like functionality with Redux using a single reducer and a single SET action. Use case: you like cursors but want benefits of Redux (time travel etc). Also because it's a fun experiment.

@faassen

This comment has been minimized.

Show comment
Hide comment
@faassen

faassen Jun 23, 2015

What is the documentation technology intended to be used? I have a lot of experience with Python restructured text and Sphinx, but I take it the React Drag & Drop website is generated using a bunch of custom scripts from markdown. That helps with flexibility (the examples in different versions of JavaScript for instance) , though I like not having to maintain code to generate my websites.

faassen commented Jun 23, 2015

What is the documentation technology intended to be used? I have a lot of experience with Python restructured text and Sphinx, but I take it the React Drag & Drop website is generated using a bunch of custom scripts from markdown. That helps with flexibility (the examples in different versions of JavaScript for instance) , though I like not having to maintain code to generate my websites.

@dariocravero

This comment has been minimized.

Show comment
Hide comment
@dariocravero

dariocravero Jun 23, 2015

Contributor

Hey guys, what do you think about adding a section on how to migrate from other (traditional) flux frameworks? I know that the migration path might not be that hard but I think it would help people get on board too. Plus, now that flummox is staying at version 4, I believe we owe it to our users... :) Thoughts?

Contributor

dariocravero commented Jun 23, 2015

Hey guys, what do you think about adding a section on how to migrate from other (traditional) flux frameworks? I know that the migration path might not be that hard but I think it would help people get on board too. Plus, now that flummox is staying at version 4, I believe we owe it to our users... :) Thoughts?

@faassen

This comment has been minimized.

Show comment
Hide comment
@faassen

faassen Jun 23, 2015

I think that's a good idea, @dariocravero, especially as it may help people understand Redux better as well -- it's another way into the documentation.

faassen commented Jun 23, 2015

I think that's a good idea, @dariocravero, especially as it may help people understand Redux better as well -- it's another way into the documentation.

@gaearon

This comment has been minimized.

Show comment
Hide comment
@gaearon

gaearon Jun 23, 2015

Collaborator

Great idea @dariocravero!

Collaborator

gaearon commented Jun 23, 2015

Great idea @dariocravero!

@vladap

This comment has been minimized.

Show comment
Hide comment
@vladap

vladap Jun 24, 2015

I think people are used to mutability, hence I think it needs to be documented what pattern to use to handle large mutable data structures which can't be copied with every mutation. And if it is either supported by Redux anyhow. I assume that immutability is the way how Redux detects changes to update views, hence I can't return a reference to a mutable whatever and this need to be clear from a documentation.

Should I create some kind of an immutable companion object with getters for underlying mutable struct which I would recreate and return as state with every update? Would this even work or it breaks other features like replay?

An example could be Crossfiler. I'm not aware of an efficient immutable equivalent. And I don't have much idea how to integrate it with Redux.

vladap commented Jun 24, 2015

I think people are used to mutability, hence I think it needs to be documented what pattern to use to handle large mutable data structures which can't be copied with every mutation. And if it is either supported by Redux anyhow. I assume that immutability is the way how Redux detects changes to update views, hence I can't return a reference to a mutable whatever and this need to be clear from a documentation.

Should I create some kind of an immutable companion object with getters for underlying mutable struct which I would recreate and return as state with every update? Would this even work or it breaks other features like replay?

An example could be Crossfiler. I'm not aware of an efficient immutable equivalent. And I don't have much idea how to integrate it with Redux.

@vladap

This comment has been minimized.

Show comment
Hide comment
@vladap

vladap Jun 24, 2015

Here are my thoughts on documenting important differences between ActionCreators vs. Actions which everybody trying to use flux/redux should be clear about. The differences are subtle but important. Feel free to rephrase it or drop it all together, I just want to log what I think can help to new users.

ActionCreator tells what should happen while Action tells what happened. ActionCreator can be understood as a Command while an Action is an event (like mouseClicked in DOM). If you come from an analytical database modeling background you would call Action a Fact (and they would be stored in a fact table in a star schema).

ActionCreators can be processed concurrently (async) and emit Actions when appropriate. Actions are processed synchronously, they can be logged to create synchronous log which can be potentially replayed (if there is such a facility).

As a sidenote, because ActionCreator term is long, people tend to shortcut it to just Action term in a general discussion (or even in a API) and freely swap them, which might be confusing at times. It could be better to have Commands and Events, or Actions (as a synonym to commands) and Events (some other eventsourcing/commandsourcing systems use these terms). But I understand the desire to stick to the original Flux terminology. For me, used to another background, it was quite confusing to decode Flux at first even there was no new concept for me.

Some more discussion about it is in #195

vladap commented Jun 24, 2015

Here are my thoughts on documenting important differences between ActionCreators vs. Actions which everybody trying to use flux/redux should be clear about. The differences are subtle but important. Feel free to rephrase it or drop it all together, I just want to log what I think can help to new users.

ActionCreator tells what should happen while Action tells what happened. ActionCreator can be understood as a Command while an Action is an event (like mouseClicked in DOM). If you come from an analytical database modeling background you would call Action a Fact (and they would be stored in a fact table in a star schema).

ActionCreators can be processed concurrently (async) and emit Actions when appropriate. Actions are processed synchronously, they can be logged to create synchronous log which can be potentially replayed (if there is such a facility).

As a sidenote, because ActionCreator term is long, people tend to shortcut it to just Action term in a general discussion (or even in a API) and freely swap them, which might be confusing at times. It could be better to have Commands and Events, or Actions (as a synonym to commands) and Events (some other eventsourcing/commandsourcing systems use these terms). But I understand the desire to stick to the original Flux terminology. For me, used to another background, it was quite confusing to decode Flux at first even there was no new concept for me.

Some more discussion about it is in #195

@vladap

This comment has been minimized.

Show comment
Hide comment
@vladap

vladap Jun 24, 2015

My anecdotal theory why Facebook decided to use ActionCreators and Actions is that "event" term is too general and in web environment too close to DOM events which could cause another confusion. In the end my preferred terminology would be Actions/Commands (instead of ActionCreators) and Facts (instead of Actions). It is how I map them internally in my mind, but it might just because of my other background (backend world).

vladap commented Jun 24, 2015

My anecdotal theory why Facebook decided to use ActionCreators and Actions is that "event" term is too general and in web environment too close to DOM events which could cause another confusion. In the end my preferred terminology would be Actions/Commands (instead of ActionCreators) and Facts (instead of Actions). It is how I map them internally in my mind, but it might just because of my other background (backend world).

@pascience

This comment has been minimized.

Show comment
Hide comment
@pascience

pascience Jun 24, 2015

Some thoughts in complement to @vladap's :
I have no "backend world" background but I use the same Action/Fact terminology and have found it to be useful both in everyday programming and when introducing the Flux architecture to coworkers.

One thing that reinforces that distinction is conjugating facts in the past tense. For instance, dispatch({ type: Facts.ASKED_TO_FETCH_DOCUMENT, documentId }) rather than dispatch({ type: ActionConstants.FETCH_DOCUMENT, ... }). In the logs, the fact in this example would be followed shortly by either FETCHED_DOCUMENT or FAILED_TO_FETCH_DOCUMENT.
In my opinion, this better represents what just happened in the app, and also makes it clear that a) the demand may not succeed and b) at the call-site, we don't care whether or when the demand gets handled.

I'm not suggesting that reduce be renamed into "fold from the past" as in Elm, but I have the impression that examples/counter would benefit from the past-tense conjugation (ie ASKED_TO_INCREMENT_COUNTER).

pascience commented Jun 24, 2015

Some thoughts in complement to @vladap's :
I have no "backend world" background but I use the same Action/Fact terminology and have found it to be useful both in everyday programming and when introducing the Flux architecture to coworkers.

One thing that reinforces that distinction is conjugating facts in the past tense. For instance, dispatch({ type: Facts.ASKED_TO_FETCH_DOCUMENT, documentId }) rather than dispatch({ type: ActionConstants.FETCH_DOCUMENT, ... }). In the logs, the fact in this example would be followed shortly by either FETCHED_DOCUMENT or FAILED_TO_FETCH_DOCUMENT.
In my opinion, this better represents what just happened in the app, and also makes it clear that a) the demand may not succeed and b) at the call-site, we don't care whether or when the demand gets handled.

I'm not suggesting that reduce be renamed into "fold from the past" as in Elm, but I have the impression that examples/counter would benefit from the past-tense conjugation (ie ASKED_TO_INCREMENT_COUNTER).

@gaearon gaearon referenced this pull request Jun 24, 2015

Closed

Transducers in Redux #176

@vladap

This comment has been minimized.

Show comment
Hide comment
@vladap

vladap Jun 25, 2015

Past tense works well for facts which happened. But I was thinking about it yesterday and I think I switched my understanding of Flux.

As I understand:
Eventsourcing system is based on a log of facts which happened. Facts are logged after complex processing. Eventsourcing system process them synchronously and when it starts with state A and applies the log to it always ends with state B. Hence this system can be replayed.

Commandsourcing system is when I log a command before any processing happens. To replay such a system then processing of each command has to be deterministic. In today concurrent world with Service Oriented Architectures, microservices and such, it is impossible to build replayable commandsourcing system as a whole.

Flux:
Flux doesn't log commands (actions) before any processing happens but it logs commands after all non-deterministic processing is done. Subsequent commands (actions) processing is strictly synchronous and potentially replayable. Hence I don't have to log facts and I can log commands (actions).

With this understanding actions doesn't log fact what happened but actually what should happen.

The only issue is that different developers try to grasp Flux either as eventsourced app or general commandsourced app while it is a special case of a command sourced app. Flux can be a small part of my whole system which can afford to work as synchronous command sourced app. There still can be many other non-deterministic async services around, like WebApiTools.

Hope, it makes sense to anybody. Let me know if I should tweak my understanding more and I'm still off.

Some more discussion about it is in #195

vladap commented Jun 25, 2015

Past tense works well for facts which happened. But I was thinking about it yesterday and I think I switched my understanding of Flux.

As I understand:
Eventsourcing system is based on a log of facts which happened. Facts are logged after complex processing. Eventsourcing system process them synchronously and when it starts with state A and applies the log to it always ends with state B. Hence this system can be replayed.

Commandsourcing system is when I log a command before any processing happens. To replay such a system then processing of each command has to be deterministic. In today concurrent world with Service Oriented Architectures, microservices and such, it is impossible to build replayable commandsourcing system as a whole.

Flux:
Flux doesn't log commands (actions) before any processing happens but it logs commands after all non-deterministic processing is done. Subsequent commands (actions) processing is strictly synchronous and potentially replayable. Hence I don't have to log facts and I can log commands (actions).

With this understanding actions doesn't log fact what happened but actually what should happen.

The only issue is that different developers try to grasp Flux either as eventsourced app or general commandsourced app while it is a special case of a command sourced app. Flux can be a small part of my whole system which can afford to work as synchronous command sourced app. There still can be many other non-deterministic async services around, like WebApiTools.

Hope, it makes sense to anybody. Let me know if I should tweak my understanding more and I'm still off.

Some more discussion about it is in #195

You'll rarely interact with the store object directly. Most often, you'll use some sort of binding to your preferred view library.
Flux is most popular within the React community, but Redux works with any kind of view layer. The React bindings for Redux are available as react-redux — see that project for details on how to integrate with React.

This comment has been minimized.

@dferber90

dferber90 Jul 15, 2015

Contributor

"Flux is most popular within the React community"
Did you mean "React is most popular within the Flux community," instead?

@dferber90

dferber90 Jul 15, 2015

Contributor

"Flux is most popular within the React community"
Did you mean "React is most popular within the Flux community," instead?

This comment has been minimized.

@gaearon

gaearon Jul 15, 2015

Collaborator

Hmmm.. I still think React community is bigger than Flux community :-)

@gaearon

gaearon Jul 15, 2015

Collaborator

Hmmm.. I still think React community is bigger than Flux community :-)

This comment has been minimized.

@dferber90

dferber90 Jul 15, 2015

Contributor

That's true :-) I was suggesting the switch because of the second part of the sentence.
In my mind the current wording suggests Flux is the "view layer", which seems wrong.

Flux is most popular [as a view layer] within the React community, but Redux works with any kind of view layer.

Anyways, great work on Redux and the new docs 👍

@dferber90

dferber90 Jul 15, 2015

Contributor

That's true :-) I was suggesting the switch because of the second part of the sentence.
In my mind the current wording suggests Flux is the "view layer", which seems wrong.

Flux is most popular [as a view layer] within the React community, but Redux works with any kind of view layer.

Anyways, great work on Redux and the new docs 👍

This comment has been minimized.

@hasdavidc

hasdavidc Jul 16, 2015

i agree with @dferber90 - the phrasing suggests that React's most popular view layer is Flux

@hasdavidc

hasdavidc Jul 16, 2015

i agree with @dferber90 - the phrasing suggests that React's most popular view layer is Flux

This comment has been minimized.

@AprilArcus

AprilArcus Jul 16, 2015

Contributor

"Although Flux architectures were originally popularized within the React community, Redux works with any kind of view layer."

@AprilArcus

AprilArcus Jul 16, 2015

Contributor

"Although Flux architectures were originally popularized within the React community, Redux works with any kind of view layer."

```js
const boundAddTodo = text => dispatch(addTodo(text));
const boundRemoveTodo = id => dispatch(addTodo(id));

This comment has been minimized.

@hasdavidc

hasdavidc Jul 16, 2015

const boundRemoveTodo = id => dispatch(removeTodo(id));
@hasdavidc

hasdavidc Jul 16, 2015

const boundRemoveTodo = id => dispatch(removeTodo(id));
const store = newCreateStore(reducer);
```
If you

This comment has been minimized.

@hasdavidc

hasdavidc Jul 16, 2015

incomplete phrase

@hasdavidc

hasdavidc Jul 16, 2015

incomplete phrase

dispatch => dispatch'
```
The key feature of middleware is that it is composable. Multiple middleware can be combined together, where each middleware requires no knowledge of the what comes before or after it in the chain.

This comment has been minimized.

@hasdavidc

hasdavidc Jul 16, 2015

orphan the - "requires no knowledge of what comes"

@hasdavidc

hasdavidc Jul 16, 2015

orphan the - "requires no knowledge of what comes"

Show outdated Hide outdated docs/middleware.md
Yes, you read that correctly. If this looks strange to you, it may help to break the process down into multiple steps:
```js

This comment has been minimized.

@hasdavidc

hasdavidc Jul 16, 2015

could use the same comment that was in getting-started.md:

// where promise, thunk, and observable are examples of middleware
@hasdavidc

hasdavidc Jul 16, 2015

could use the same comment that was in getting-started.md:

// where promise, thunk, and observable are examples of middleware
const state = store.getState(); // somehow pass this state to the client
// client
const initialState = window.STATE_FROM_SERVER;

This comment has been minimized.

@hasdavidc

hasdavidc Jul 16, 2015

duplicated as in universal-rendering.md - intentional?

@hasdavidc

hasdavidc Jul 16, 2015

duplicated as in universal-rendering.md - intentional?

@AprilArcus

This comment has been minimized.

Show comment
Hide comment
@AprilArcus

AprilArcus Jul 16, 2015

Contributor

I remade @erikthedeveloper's diagram with the Counter example from 1.0rc. Atom + Babel-Sublime + Base16 Eighties + Menlo > OS X CoreText @ 2x HiDPI mode > a little fussing in photoshop > some clumsy beziers in Omnigraffle. Please use if useful or request corrections/updates if desired.

Contributor

AprilArcus commented Jul 16, 2015

I remade @erikthedeveloper's diagram with the Counter example from 1.0rc. Atom + Babel-Sublime + Base16 Eighties + Menlo > OS X CoreText @ 2x HiDPI mode > a little fussing in photoshop > some clumsy beziers in Omnigraffle. Please use if useful or request corrections/updates if desired.

@emmenko

This comment has been minimized.

Show comment
Hide comment
@emmenko

emmenko Jul 16, 2015

Collaborator

@AprilArcus wow, nice!! 👍

Collaborator

emmenko commented Jul 16, 2015

@AprilArcus wow, nice!! 👍

@AprilArcus

This comment has been minimized.

Show comment
Hide comment
@AprilArcus

AprilArcus Jul 16, 2015

Contributor

I think this might look better with the long form of the HOC, so we can see the dependency injection of counter into CounterApp's props.

I think it might also be interesting to (maybe on another layer?) annotate the import tree in another color. Maybe state, actioncreator, and action should be annotated in different colors or line styles, with a legend? Maybe color or line style should be used to distinguish "imports" from "dependency injects" from "calls"?

Maybe App.js should be included?

Maybe the spiral of perpetual-application-to-return-value would look good broken out into the flow of data through the Redux source code?

Contributor

AprilArcus commented Jul 16, 2015

I think this might look better with the long form of the HOC, so we can see the dependency injection of counter into CounterApp's props.

I think it might also be interesting to (maybe on another layer?) annotate the import tree in another color. Maybe state, actioncreator, and action should be annotated in different colors or line styles, with a legend? Maybe color or line style should be used to distinguish "imports" from "dependency injects" from "calls"?

Maybe App.js should be included?

Maybe the spiral of perpetual-application-to-return-value would look good broken out into the flow of data through the Redux source code?

@erikthedeveloper

This comment has been minimized.

Show comment
Hide comment
@erikthedeveloper

erikthedeveloper Jul 16, 2015

Very cool that you took that idea and ran with it here @AprilArcus! 👍

My original intention with that skitch from Twitter was to follow a single piece of data flowing end-to-end through the "Redux cycle" (Reducer -> Container -> Component -> Action -> Reducer [...])

[...] request corrections/updates if desired

My only suggestion would be to simplify it as an illustration of the "flow of data" rather than trying to cover all the bases and highlighting too many details in one screen grab. I feel like the number/complexity of the arrows could be simplified (I prefer straight arrows w/ one arrow entering and one arrow exiting each area/concept) to illustrate the "flow" rather than "connecting all the dots".

I would also hide the line numbers and change the arrow color to contrast w/ the code/text. Just my preference 😄

Merely a suggestion/preference to simplify to better reflect the simplicity of Redux. Great to see it pop up in this conversation!

Original

image

Possible suggested simplification of April's

ignoring green arrows/boxes

image

erikthedeveloper commented Jul 16, 2015

Very cool that you took that idea and ran with it here @AprilArcus! 👍

My original intention with that skitch from Twitter was to follow a single piece of data flowing end-to-end through the "Redux cycle" (Reducer -> Container -> Component -> Action -> Reducer [...])

[...] request corrections/updates if desired

My only suggestion would be to simplify it as an illustration of the "flow of data" rather than trying to cover all the bases and highlighting too many details in one screen grab. I feel like the number/complexity of the arrows could be simplified (I prefer straight arrows w/ one arrow entering and one arrow exiting each area/concept) to illustrate the "flow" rather than "connecting all the dots".

I would also hide the line numbers and change the arrow color to contrast w/ the code/text. Just my preference 😄

Merely a suggestion/preference to simplify to better reflect the simplicity of Redux. Great to see it pop up in this conversation!

Original

image

Possible suggested simplification of April's

ignoring green arrows/boxes

image

@gaearon

This comment has been minimized.

Show comment
Hide comment
@gaearon

gaearon Jul 16, 2015

Collaborator

I agree it's better to focus on the flow than on connecting all the dots.

Collaborator

gaearon commented Jul 16, 2015

I agree it's better to focus on the flow than on connecting all the dots.

@AprilArcus

This comment has been minimized.

Show comment
Hide comment
@AprilArcus

AprilArcus Jul 16, 2015

Contributor

I see the appeal of simplifying, but I find the use of identical arrows to track values of constantly changing type (state, (state, action) => state, and () => action) to be really disorienting.

Contributor

AprilArcus commented Jul 16, 2015

I see the appeal of simplifying, but I find the use of identical arrows to track values of constantly changing type (state, (state, action) => state, and () => action) to be really disorienting.

@gaearon

This comment has been minimized.

Show comment
Hide comment
@gaearon

gaearon Jul 16, 2015

Collaborator

@AprilArcus Maybe it would help to have different pictures focusing on different arrows. Right now it's kind of hard to understand where to start and which arrow to follow.

Collaborator

gaearon commented Jul 16, 2015

@AprilArcus Maybe it would help to have different pictures focusing on different arrows. Right now it's kind of hard to understand where to start and which arrow to follow.

* [redux-react-router-async-example](https://github.com/emmenko/redux-react-router-async-example): Work in progress. Semi-official. Only the client side. Uses React Router.
* [react-redux-universal-hot-example](https://github.com/erikras/react-redux-universal-hot-example): Universal. Uses React Router.
* [redux-example](https://github.com/quangbuule/redux-example): Universal. Uses Immutable, React Router.
* [isomorphic-counter-example](https://github.com/khtdr/redux-react-koa-isomorphic-counter-example): Universal. A bare-bone implentation of the [counter example app](https://github.com/gaearon/redux/tree/master/examples/counter). Uses promises-middleware to interact with API via Koa on the server.

This comment has been minimized.

@mfunkie

mfunkie Jul 16, 2015

implentation -> implementation

@mfunkie

mfunkie Jul 16, 2015

implentation -> implementation

@AprilArcus

This comment has been minimized.

Show comment
Hide comment
@AprilArcus

AprilArcus Jul 16, 2015

Contributor

Okay, while I think about that idea, here is a non-defaced hi-res screencap of the five source files that people can mark up. Sorry I forgot to set my editor font to Consolas ^~

Contributor

AprilArcus commented Jul 16, 2015

Okay, while I think about that idea, here is a non-defaced hi-res screencap of the five source files that people can mark up. Sorry I forgot to set my editor font to Consolas ^~

Merge pull request #280 from chentsulin/patch-2
Fix a broken link in middleware.md
@arstin

This comment has been minimized.

Show comment
Hide comment
@arstin

arstin Jul 17, 2015

FWIW, I had annotated a screenshot similar to erikthedeveloper's orange lines to explain what was going on to my coworkers and it seemed helpful. I do think something similar focusing on the overall flow would be useful as a visual reference for an actual explanation. In my case, I also added numbers attached to comments describing what is happening, so the expectation wasn't that you'd be able to understand redux just from the image. On a wiki, it might make more sense to break this up into separate images with paragraphs below them?

arstin commented Jul 17, 2015

FWIW, I had annotated a screenshot similar to erikthedeveloper's orange lines to explain what was going on to my coworkers and it seemed helpful. I do think something similar focusing on the overall flow would be useful as a visual reference for an actual explanation. In my case, I also added numbers attached to comments describing what is happening, so the expectation wasn't that you'd be able to understand redux just from the image. On a wiki, it might make more sense to break this up into separate images with paragraphs below them?

@gaearon

This comment has been minimized.

Show comment
Hide comment
@gaearon

gaearon Jul 18, 2015

Collaborator

Next week @acdlite is going on a vacation so I'll take over the docs.
Happily I don't have anything else to do at the moment!

Collaborator

gaearon commented Jul 18, 2015

Next week @acdlite is going on a vacation so I'll take over the docs.
Happily I don't have anything else to do at the moment!

@tychotatitscheff

This comment has been minimized.

Show comment
Hide comment
@tychotatitscheff

tychotatitscheff Jul 19, 2015

Hi the docs from https://github.com/acdlite/flummox are hosted in github page http://acdlite.github.io/flummox .

It used an isomorphic fluxmox app to dislpay it nicely https://github.com/acdlite/flummox/tree/master/docs.

What about making the same here, if one is interessted, i can carry on !

tychotatitscheff commented Jul 19, 2015

Hi the docs from https://github.com/acdlite/flummox are hosted in github page http://acdlite.github.io/flummox .

It used an isomorphic fluxmox app to dislpay it nicely https://github.com/acdlite/flummox/tree/master/docs.

What about making the same here, if one is interessted, i can carry on !

@gaearon gaearon referenced this pull request Jul 19, 2015

Closed

Rewrite the docs #289

@gaearon

This comment has been minimized.

Show comment
Hide comment
@gaearon

gaearon Jul 19, 2015

Collaborator

Superseded by #289. Docs written here will be gradually moved over there.

Collaborator

gaearon commented Jul 19, 2015

Superseded by #289. Docs written here will be gradually moved over there.

@gaearon

This comment has been minimized.

Show comment
Hide comment
@gaearon

gaearon Jul 23, 2015

Collaborator

Want to help with the new docs?
I created the initial directory structure: https://github.com/gaearon/redux/tree/rewrite-docs/docs/

If you'd like to help and maybe write a few recipes, let me know in #289 so we can collaborate.

Collaborator

gaearon commented Jul 23, 2015

Want to help with the new docs?
I created the initial directory structure: https://github.com/gaearon/redux/tree/rewrite-docs/docs/

If you'd like to help and maybe write a few recipes, let me know in #289 so we can collaborate.

@gaearon gaearon referenced this pull request Jul 28, 2015

Closed

Rewrite docs (again!) #349

@gaearon gaearon deleted the improve-docs branch Aug 6, 2015

@tsingson

This comment has been minimized.

Show comment
Hide comment
@tsingson

tsingson commented Aug 12, 2015

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment