Docs improvements

[acdlite]

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

• Rename Stores to Reducers
• Rename the “Redux instance” to Store as per Proposal: Rename "stores" to "reducers" #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 I want to use "Dumb Components" #134 (comment)
• Higher-order stores (possibly call these "store transformers"?)
• Full API docs
• Touch on sugar like createReducer, createActionCreators haha
• Anti patterns (e.g. Trying to put API calls in the correct place #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.

[emmenko]

👍

[acdlite]

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]

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]

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]

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]

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]

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]

Great idea @dariocravero!

[vladap]

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]

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]

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).

[najmam]

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).

[vladap]

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

[gaearon]

@acdlite Have you had any chance to work on this yet? Not pushing, just checking up. I'm going to be available to work on this right after React Europe.