Docs: Improve Epics introduction

[jorisw]

If Epics are indeed the core primitive of Redux-Observable, then I believe the intro for it does a bad job at getting its concept and purpose across. I would improve it myself if I knew how. Therefore I'm sharing my experience of reading it as a conversation:

An Epic is the core primitive of redux-observable.

Great. What purpose does it serve? Is it a way to functionally implement the effect of a particular action?

(It would have been so much better if instead of "Epic", a descriptive name was chosen for these. This is your core concept, and you're hiding it behind some random word that is already used in all kinds of other contexts?)

It is a function which takes a stream of actions and returns a stream of actions. Actions in, actions out.

Cool. So that's the functional constraint of using Epics. However if the same type goes in, as comes out, is there any real functional implementation going on in the mean time? Does the Epic take an action, then implement some kind functionality, then output an action? This is what needs to be described clearly in order for Epics to be conceptually conveyed, before moving on to technical descriptions or usage examples.

It has roughly this type signature:

function (action$: Observable<Action>, state$: StateObservable<State>): Observable<Action>;

No need to get this technical about it now IMHO, at least not before the concept is better described.

While you'll most commonly produce actions out in response to some action you received in, that's not actually a requirement! Once you're inside your Epic, use any Observable patterns you desire as long as any output from the final, returned stream, is an action.

This directly contradicts "Actions in, actions out" in my mind. If I'm wrong about that, the docs should explain how so.

I hope this helps in improving the Epics intro, and I'd be happy to assist further.

[evertbouw]

Epics receive a stream of actions and map it to a new stream of (zero to many) actions
Meanwhile they can perform based on the result of performing side effects.

[joriswitteman]

That alone would sure be a helpful addition to the intro.