RFC: [Learning team] Onboarding tutorial for ReactiveUI

[havremunken]

When I start using a new library or framework, there are two things I really appreciate: Good reference docs, and a tutorial showing me WHY this is a good idea and HOW to get going.

I'm talking about addressing the newborns here. The people who may have heard about Reactive Extensions, who perhaps gets the basic concept of a viewmodel, but when they look at the RxUI docs site will look like a huge question mark and think "How will any of this ever be useful to me?" - the people that need motivation to join us.

So I thought as my first contribution to the learning team, I could get going on on this "onboarding" tutorial. The "Welcome to ReactiveUI" bit. Once again my primary source of inspiration as I write this is how the Ember.js project has done it. Take a look at their guides site here:

https://guides.emberjs.com/

This will take you to a friendly site that promises to take you from total beginner to expert. Ambitions are good!

As you can see, it has a bunch of subsections. First "Getting Started" shows you how to get it onto your system and explains core concepts. Then the tutorial goes through every step of creating an app from planning to deploying. Each page is relatively short, explains the relevant concepts well, and has source code listings aplenty. They even spend time showing how you test these features as you learn them to get into good habits early.

A similar (updated) tutorial for RxUI would be extremely useful (I've missed it in the past myself). As pointed out in my other docs-related RFC we might need to allow the user to choose the platform they want guidance on - the main structure of the tutorial would probably be the same, but that would mean several versions of each page with custom text, source code and screenshots for each platform.

In my mind, we would need to come up with one simple, understandable but still real-world-relevant example to follow through the entire tutorial. It would make sense to write a ViewModel object using plain C# to see how awful the world is without RxUI (note: Would it be a good idea to show how this could be done in other UI frameworks as well, to help people coming from there to us?), and then step by step improve it using observables and friends. It could start with a short explanation of how MVVM is The Right Path and reactive extensions are awesome, and then show how RxUI lives at the intersection of these two concepts.

I believe such a tutorial is a good idea, but since I am new to the project I would love some input on this RFC before I start working on it. So please feel free to disagree or add additional points that would be good to include. The primary goal of this RFC is to create something that makes users WANT to use RxUI for everything.

[S3bt3r]

I totally agree with you!

A similar (updated) tutorial for RxUI would be extremely useful (I've missed it in the past myself). As pointed out in my other docs-related RFC we might need to allow the user to choose the platform they want guidance on - the main structure of the tutorial would probably be the same, but that would mean several versions of each page with custom text, source code and screenshots for each platform.

That would be a lot of work, but in my opinion the best way!

[kentcb]

Love the idea.

Regarding the real-world example, I'd recommend something with real-time requirements. For example, throttling user input so that an asynchronous action is not kicked off too many times. In addition, multiple asynchronous commands, of which any's execution should maintain a single IsBusy flag. These things are quite messy to implement without Rx(UI).

On my TODO list is to start a "bootstrapping" section in the docs. That is, step-by-step instructions for how to create a solution, add RxUI to it, and get a minimal VM up and running. My current plan is to do a guide for both WPF and XF, leaving the rest to others. Do you think we'd be stepping on each other's toes here, or would these live comfortably alongside each other in the docs?

[RLittlesII]

@kentcb I think it depends on what we mean docs. Currently the only documentation I am aware of is the generated API and docs that live on the ReactiveUI website. It seems like there is an opportunity here to create a true tutorial site. I think we should take a systematic approach like they did on the RX Marbles site and others. That way we can divide and conquer specific examples to help consumption.

I like your boiler plate idea. Maybe we have a set of repositories you can clone as starter templates? Maybe we make those templates available through tools so people could either clone the repo, or download the template and have a full ReactiveUI boilerplate app to start writing their logic against without having to scaffold the project themselves?

[lythix]

Love the idea on tutorial site. The thing I love about docs.microsoft.com are the examples. Generated docs from APIs make me sad. Even a single code example on how to USE the thing make me happy. I'm adding myself to the learning team to help make this reality. Also, confession: I'm an rx noob and so am taking special note on the pain points as I learn. :)

[ghuntley]

I'm 10,000% about doing and supporting this.

The plan is to get reactiveui running in the web-browser at the URL of https://try.reactiveui.net/ with an experience similar to http://rxviz.com/

The workbooks folks have cooked us up something special to make this a reality and you can see initial workings over at http://github.com/reactiveui/try.reactiveui.net. This tech exists right now. I'd love to pair with folks to finish off the ReactiveUI integration side of things.

Once the technology side of things are in place we will also need actual tutorials developed as well.

[terrafied]

I agree with full context and working code as much as possible-- with the ideal of embedding working code directly into the examples. I've spent the majority of today reading the documentation/answers and finding examples in multiple syntaxes/naming schemes. As best I can determine, the current website documentation seems to be a mix of versions (And non-website documents are certainly out of date).

For example, I see some old ReactiveUI.Samples code that seems to use ReactiveCommand<object> and compiles (library version 6.0), but with my project, that is a compile-time exception, and I can only get ReactiveCommand<Unit, Unit> to work (8.0).

I chose to use ReactiveCommand<Unit, Unit.> only because the documentation on the "An Example" page shows that syntax. I got a bit confused around the ViewModel page though, because it shows ReactiveCommand<object> as the syntax.

For the newborns like me, it is extremely confusing when documentation is not in tune with itself. Not only because of the inability to use current examples without researching, say, the translation to the new library version, but because there is not a full context in the documentation. (The ViewModel page seems to show code that is not necessarily related to another page. Read that page with the eyes of a newbie who's not muscle-memory comfortable with what OneWayBind means or not even really comfortable with how to connect the view and view model well in a Reactive framework.)

Tying our documentation to a codebase that compiles and embedding that code's master branch to the documentation (or at least using a unified example that we know compiles) would save a lot of frustration here and provide some much needed context that the current documentation assumes but does not necessarily provide.

I also think tutorials could actually utilize the same codebase. The documentation is a snapshot of that codebase from an interaction perspective, but the tutorials can be roadmaps for "how did we get there" on particular topics.

(sorry, that was a bit of a rant. PRs are coming on the website at least)

[lythix]

What is the correct location for the tutorials and accompanying tutorial code?
In samples folder in ReactiveUI folder, in website repo under tutorials section, or in ReactiveUI.Samples repo? Or some other location I have not yet found?

[terrafied]

@lythix I think that's still TBD.

[ghuntley]

Guidance:

• The website is configured to download the contents of reactiveui/reactiveui/src/*.csproj as part of every deploy of the website. The contents are used to generate https://reactiveui.net/api via WYAM. I've configured daily builds in VSTS so even if there's PR merges the max drift is always 24 hours.

• Samples are in reactiveui/reactiveui and should in theory (yet not in practice yet) be kept up to date as part of PR'ing master.

• In the future.... we could move the contents of reactiveui/website/input/docs/* into reactiveui/reactiveui and mandate that documentation (and samples) must be updated before a PR is merged/approved. I would be supportive of this.

Thanks for pointing out that reactiveui/ReactiveUI.Samples still existed. It should have been retired. I've made the repo private. Double down on improving reactiveui/reactiveui/samples/*

[havremunken]

@kentcb

Regarding the real-world example, I'd recommend something with real-time requirements. For example, throttling user input so that an asynchronous action is not kicked off too many times. In addition, multiple asynchronous commands, of which any's execution should maintain a single IsBusy flag. These things are quite messy to implement without Rx(UI).

Absolutely important point - in order to "sell" ReactiveUI, we need to focus on those issues that we do better, easier, clearer than the alternatives. Of course I want to show RaisePropertyChanged() too, but I don't think that is where any of us fell in love with RxUI. ;) So yes, real world, dirty, hairy requirement that makes sense to do in a reactive way.

However, this leaves another thought in my head about samples for commonly seen challenges and how to solve them correctly. Will ponder.

On my TODO list is to start a "bootstrapping" section in the docs. That is, step-by-step instructions for how to create a solution, add RxUI to it, and get a minimal VM up and running. My current plan is to do a guide for both WPF and XF, leaving the rest to others. Do you think we'd be stepping on each other's toes here, or would these live comfortably alongside each other in the docs?

From my perspective, these will complement each other nicely. We could even exchange content where it makes sense. Avoiding duplication of effort is a good thing, but the primary goal is that a new RxUI user should feel welcome and taken care of, and I am certain we can do that with a minimum of toe-stepping.

@ghuntley The RxUI in the browser sounds like a HUGE win. I haven't had a chance to test it yet, but for the tutorial, the ability to visualize things could mean the difference between failure and success in getting someone to grok how all this fits together.

@lythix I tried to construct some thoughts on that over at #4, but of course there is stuff already in place so I'm not gonna pretend like I know the right way forward. However, to summarize it - let us try to make it as easy as possible to contribute to the docs. Low friction, low threshold, multiple sets of eyes on stuff to make sure we have a bit of quality control.

And I am almost done reading Kent's book so hopefully I'm reaching a point where I am actually competent with the framework, which should probably be a requirement for attempting to teach it to others. ;)

[ghuntley]

Let's keep this thread about the actual content and first-time experience. All conversation about interactive documentation (the technology) in the browser should be forked over to #8

[lythix]

I had a look at the generated API docs and noticed there are no examples there.
We need some way of including examples of a particular usage of an API right there on the generated docs. Some of them are quite lengthy. This might be its own RFC, but as its content related I put it here for now.

[RLittlesII]

@lythix Wyam allows for us to put examples in the code. It will pick up anything marked public.

        /// <example>
        ///   <code>
        ///     SqlPackageExtract(settings =>
        ///     {
        ///         settings.Quiet = true;
        ///     });
        ///   </code>
        /// </example>

I haven't dug far enough into the ReactiveUI code base, but I will say, this can potentially bloat the code files. We can discuss further here #4