RFC: [Learning team] Onboarding tutorial for ReactiveUI about rfcs HOT 13 OPEN

from rfcs.

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

from rfcs.

@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

from rfcs.

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!

from rfcs.

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?

from rfcs.

@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?

from rfcs.

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.

from rfcs.

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)

from rfcs.

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?

from rfcs.

@lythix I think that's still TBD.

from rfcs.

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/*

from rfcs.

@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. ;)

from rfcs.

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.

from rfcs.