Docs: Strategy for Guides

[rgbkrk]

While I have the enthusiasm for it, I'd love to kick out more docs for RxJS 5. Especially those that are user focused guides with examples. Let me know how and where and I'll start putting out some.

[anthonybrown]

Awesome, I'd love to learn more about this awesome library

[benlesh]

@staltz is working on updating reactivex.io. Perhaps he can comment here on that effort. Otherwise, we need work done to update code file documentation for the ESDocs we generate that are published to reactivex.io/RxJS.

cc/ @staltz

[staltz]

I'm working on updating the basics of reactivex.io (just updating every mention of RxJS to be aligned with RxJS 5's API), which is a cross-platform documentation site. It sorts of limits how we can document the API, because everything is "framed" as cross-platform. For instance http://reactivex.io/documentation/operators/scan.html the structure is: (1) the operator explained in high-level for all languages, (2) RxJS specific variants and a simple example for each variant.

(2) is not really an appropriate space to elaborate on each operator.

I need more suggestions on what would be the ideal documentation site for RxJS 5. And then how we can fit that either in reactivex.io or the ESDocs.

[Widdershin]

Definitely keen to contribute to some user focused documentation, especially with interactive examples.

[staltz]

@Widdershin one thing which I think can be independently built and embedded anywhere is the decision tree https://github.com/Reactive-Extensions/RxJS/blob/master/doc/gettingstarted/which-instance.md in an interactive form. I imagine a series of questions displayed and answering one takes to another question, until you hit the last answer and the conclusion is the operator you should use.

[HighOnDrive]

@staltz How about letting the visitor coming to the reactivex.io home page make a choice for what language (JS, Java, etc) they want to view the rest of the site in? This would work similar to how a locale (English, French, German, etc) can be selected on internationalized sites.

If the visitor chooses RxJS then a given operator page would (1) have the header still explain the operator in high-level for all languages, (2) have everything else on the operator page be displayed in RxJS or an alternate language the visitor may have selected.

This would let the whole operator page be used for the selected language and completely remove the need to dig through more obtrusive menus. The language choice can be stored in a cookie so it is remembered on return visits, yet it can be changed at any time.

[staltz]

@HighOnDrive that's a great idea, but to minimize development effort (and keep the page static, not a SPA), I'd do it so that choosing a prog language would redirect you to a sub page.

@blesh what do you think about this? We could propose it to folks handling reactivex.github.io

[benlesh]

It sounds good to me. I think most people are there for a language of choice anyhow.

[staltz]

And it feels really weird to try to fit it together with other languages. The categorization gets messed up sometimes. e.g. withLatestFrom as a variant of combineLatest.

[HighOnDrive]

@staltz There is a nice example of a language switcher in this API guide: http://rethinkdb.com/api/javascript/

[staltz]

@HighOnDrive thanks. We may take a different approach though.

Here's a draft I have based on our ESDocs site: http://reactivex-rxjs5.surge.sh/

The idea is to put explanations of concepts besides the existing reference.

[HighOnDrive]

@staltz Great to see the documentation starting to take shape, looking good. It would also be nice to have some operator by category and operator decision table fast access icons in the header, next to the handy search field. Like the marble diagrams!

[SomeKittens]

One of the biggest issues for me in the v4 docs back when I was learning Rx was the confusing vocabulary. I'd love for v5 docs to have better explanations as to what the terms we're throwing around (Scheduler, Sequence, Selector Function, etc). I think the current v4 docs are great but oriented towards folks who already know what they're doing. I think the current effort to make v5 docs more newcomer-friendly is fantastic.

[staltz]

Don't worry, I'll keep it beginner friendly as much as possible. I really know what you mean with the v4 docs. ;)

[giltig]

BTW I meant for this: http://reactivex-rxjs5.surge.sh/ As unclear and complicated. I do support a separate website for only rxjs docs with great explanations such as Andre stalz introduction to rx

[anthonybrown]

Would appreciate the beginner friendly docs, just getting up to speed with ES6 syntax.

[SomeKittens]

Come to think of it, if this is a whole site, runnable documentation would be awesome. Has there been any effort to allow debugging with a RxMarbles-like interface? The live visualization would help a lot.

[dreambo8563]

+1 we really need the friendly docs to help us learning rxjs.

[benlesh]

I'm going to close this issue as stale. Because:

1. We're definitely working on the documentation. It's a top priority.
2. This issue doesn't have much to it that's actionable, so it'll be hard to close/resolve.

I want to deeply thank everyone in this issue for their input. Your desires are being taken to heart.

[anthonybrown]

Thanks Ben.

On Mon, Mar 21, 2016 at 4:05 PM, Ben Lesh notifications@github.com wrote:

Closed #1242 https://github.com/ReactiveX/rxjs/issues/1242.

— You are receiving this because you commented. Reply to this email directly or view it on GitHub https://github.com/ReactiveX/rxjs/issues/1242#event-597699924

~ Tony Brown

Email: tony@tonybrown.me Site: http://tonybrown.me Skype: tonyb6778 Twitter: https://twitter.com/pixelBender67 LinkedIn: https://www.linkedin.com/in/tbdesign Dribble: https://dribbble.com/pixelBender67

[rgbkrk]

Sounds good to me, thanks all. I'll keep being a user and writing tutorials. :)

[lock[bot]]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.