Please put old docs back, as too much is missing in the new ones

[dietergeerts]

Documentation Related To Component:

Several ones

Please check those that apply

• [ ] typo
• [x] documentation doesn't exist
• [ ] documentation needs clarification
• [ ] error(s) in example
• [ ] needs example

Description Of The Issue

Several components are missing documentation, like switchAll. + There is no possibility to see the old docs from it, which makes it hard to check them out. That's why the old docs should still be accessible!!!

[niklas-wortmann]

So basically the old docs are still available -> http://reactivex.io/rxjs/manual/index.html You just can't go to the home page, there you will be redirected to the new docs. But besides that, could you maybe elaborate what else is missing. SwitchAll is poorly documented absolutely right. But if you help me with that kind of feedback, I can improve the new docs, to make them more useful for everyone.

[001123]

I wish have new docs for rxjs 6 above 🙏

[dietergeerts]

But why redirect when the new docs aren't complete yet? Better to give the option then, no?

[ahahn95]

Do we know when the new docs will be available? I'm pretty excited about rxjs6, but it might as well be DOA for me without docs..

[pertrai1]

@ahahn95 you can find the new docs for version 6 at http://reactivex.io/rxjs. Each day more and more of the docs are getting updated. If there is any documentation you find missing that would help you, please share in this thread.

[ahahn95]

@pertrai1 Sure, I'm specifically looking for the ajax docs. (importing ajax from 'rxjs/ajax' etc etc)

[pertrai1]

@ahahn95 the docs are being built from JSDocs from each of the files. I am not sure why this is not added, and I am in the process of finding out. In the meantime, you can take a look at the file and see the JSDocs for the ajax.ts file: https://github.com/ReactiveX/rxjs/blob/master/src/internal/observable/dom/ajax.ts

Will find out about this for you in regards to showing in the actual docs.

[cartant]

@pertrai1 Regarding the ajax docs inclusion in the build, see this recent PR: https://github.com/ReactiveX/rxjs/pull/3984

[ahahn95]

"It creates an observable for an Ajax request with either a request object with url, headers..."

So I assume it would look like

ajax({
    url: 'http://myurl.com',
    headers: {
        ...
    }
})

[alphashuro]

The fact that the docs redirect to the new incomplete version has been quite painful for me too, and added extra barriers in teaching people how to use RxJS as well. It would be extremely beneficial if you let the docs url point to the old docs, perhaps make a banner that draws attention to the fact that they are old, and add an option to view the new docs from there. I understand that you are willing to listen to all the complaints here and use them to decide what to focus on in the docs, but I think its safe to say that everything will need to be documented.

I would get a lot of value from the old docs because:

1. The descriptions and syntax definitions were quite good, and I frequently want to make reference to them when I know what I want to do but can't remember exactly what the function is called or in what order it takes its arguments
2. It is an invaluable resource when explaining to someone the benefits of rxjs and showing them how to adopt it. The old docs had examples and explanations for every function, whereas if I were to wait for doc updates every time I want to explain something to someone, it becomes quite discouraging for both parties. Consider how scary it is for someone who has just been introduced to this thing called observables, they've been told that it will make their code better but don't quite understand how to use it yet, only to find out the docs for it are incomplete.

It is also important to consider that since the new docs are in development there will be some bugs frequently, creating yet another barrier to getting the information we need. I'm certain many people would be glad to help test out the new docs and share information on bugs when I find them, but when people need to get things done quickly they tend to require a complete reliable and quick reference source. I currently almost always end up digging up the old docs to find the information I need, with the most recent example being Observable.create.

[pertrai1]

I do propose that we keep all people in mind when it comes to the docs. With that said, I would like to see the v5 docs be the main starting point with a banner that lets people know how to get to the v6+ docs. If the older docs are helpful in any way to people, there should be an obvious way to get to them. My vote is to have either the old docs as they starting point with a banner for v6 docs, or a page that has 2 buttons that would point to either the v5 or v6 docs.

[dietergeerts]

Yes, I tried the new docs this week, and there is too much missing, even the diagram pictures are missing, which are needed to understand what's happening quickly.

[IgnusG]

New to rxjs and I basically have to jump back and forth to understand what is going on. The new documentation provides only the bare minimum which, for a beginner, is by far not enough.

[niklas-wortmann]

Hi @IgnusG I can totally understand that, and I'm really sorry for that. But I would really prefer improving the new docs rather than improving the old and the new one. I would be really interested in what is missing for you? We just started migrating the content of the old docs but I like to get feedback of what is really needed by the community. Thank you very much!

[dietergeerts]

@JWO719 , marble diagrams, descriptions, examples, ….. A LOT of methods only have their typings documented, with no way to click through to what some typings mean.....

[IgnusG]

As @dietergeerts summed up. (Sorry for the long rant - trying to cover everything) I'm missing an organized structure like in the old docs where you can quickly find your way around. In the new ones you have to guess pretty much what is called what to find it using the search bar.

VS

I'm missing marble diagrams (amazing tool to glance and understand how an operator works btw. - awesome work on that in the old docs).

The new docs are also harder for me to follow:

• The signature is bigger than the top description (I rarely look at the signature - you can do that with a smart enough IDE or source code of typings)
• Parameters table is missing the type (you have to look up to the signature to find out the type)
• Why would "See Also" be in the middle? I wanted to look at the method, not check other ones. It can safely be at the bottom of the doc page like in the old one.

2 images for comparison of the pluck method (The new one takes up more space while providing less information):

Maybe its just me, but I can really navigate the old ones better than the new ones. I usually look at the old ones and then check the new ones to see if there have been any differences between versions.

[niklas-wortmann]

Thanks for this input. That is really valuable. Regarding your points: missing structure: I think you are mostly talking about the static content describing all the stuff. We currently try to migrate this, just for your information. missing marble diagrams: this is a current bug in the deployed version of the docs. Normally there are the same marble diagramms and they will be again soon. api docs: regarding the order of the elements you got some valid points. I'll think about it.

Thanks for this valuable input.

[karptonite]

@JWO719 Any update on the missing marble diagrams? They are super useful!

[niklas-wortmann]

We hope that we fixed it finally but its not deployed yet.

[karptonite]

@JWO719 thanks, but is there no process to accelerate the deployment of the docs? This has been a problem for a long time, and I’m sure is especially frustrating to those who are trying to learn the library.

[kievsash]

Just created a doc (article) about queue vs null scheduler difference. Do we have some documentation issue where i can post it? (https://medium.com/@alexanderposhtaruk/so-how-does-rx-js-queuescheduler-actually-work-188c1b46526e)

[magnusriga]

Wanted to hop on here. Loved the old operator explanations and marble diagrams. Understanding operations like switchMap from the new docs is significantly harder.

[niklas-wortmann]

I will close this issue for now, as there is not much traffic and for now there is no plan to continue mainting the old versions of the docs. If there are any new concers, feel free to reopen or create a new issue