Rxjs: [Docs] add compare section in documentation

Created on 12 Dec 2018 · 5Comments · Source: ReactiveX/rxjs

I think it would be valuable to have a dedicated section in the docs where we compare similar operators.
I often see devs struggle with this particular issue. e.g. "should I use flatmap or switchmap for this usecase".
Also that's a point we can't make very clear in the api docs because there we are focused on that single operator.
For now I don't have any precise idea about the structure and the content itself. I just wanted to raise that idea so that it doesn't get lost :D

Feedback appreciated

docs

Source

niklas-wortmann

👍2

Most helpful comment

There is a practical example that covers all four of the flattening operators in this article (of mine): https://link.medium.com/XZKkTzAfAS

cartant on 12 Dec 2018

👍3

All 5 comments

Great idea. combineLatest, forkJoin and zip would be another one to cover, alongside switchMap, concatMap and mergeMap. These are the two sets that I find myself explaining most often I think.

I'm also not sure what the best format would be, but I'm thinking something with a practical example might be best. When explaining switchMap, concatMap and mergeMap I often use the concept of a search box that is emitting a stream of user input changes. That stream is then switch/concat/merge mapped to some async call for search results. In that context you can explain the different results you would get from the three operators, and say why in this case switchMap is (probably) the one you want.

jgbpercy on 12 Dec 2018

There is a practical example that covers all four of the flattening operators in this article (of mine): https://link.medium.com/XZKkTzAfAS

cartant on 12 Dec 2018

👍3

@JWO719 maybe there should be considering putting together an editorial team that can work on content such as this. The team could meet and put together plans for how to get content out to the public. Also, consideration should be taken for having the external resource section where content can be assembled for anyone looking for more deep dive other than source code.

pertrai1 on 14 Dec 2018

https://github.com/btroncone/learn-rxjs has sections for operators grouping them based on use case.

The docs are currently a bit confusing I think because you don't exactly know whether or not you want to use the new docs at https://rxjs-dev.firebaseapp.com but then that's basically just API documentation without the guides and intro from the old docs. I reckon that's a no-starter for beginners...