Docs: need actually explain what this framework is, why you should use it, and how it works

[Aaronontheweb]

As far as documentation goes, this project is very difficult to follow - and I described as such on this thread: https://twitter.com/Aaronontheweb/status/1395030897779433472

I wanted to offer some suggestion so you can help users get up and running with Reaqtor quickly

1. https://reaqtive.net/ - "Meet Reaqtor" takes you to a stemwinder of a blog post about how Reaqtor came about. That's great, but what does Reaqtor do and why should I care? Add a link to a short video or a short post that adds some meat to the bones of Reaqtor's elevator pitch on the homepage.
2. https://reaqtive.net/documentation/ - begins with an explanation of all of Reaqtor's modules within the framework. No one cares. Start with a conceptual overview of what Reaqtor is, what problems does it solve, and why / when you should use it. Introduce the framework architecture later - people who are deep enough into Reaqtor to care about those details will find them.
3. Add a basic "Hello World" use case that demonstrates the 20% of Reaqtor 80% of applications need in order to run. Samples like https://github.com/reaqtive/reaqtor/blob/main/Reaqtor/Samples/IoT/Reaqtor.IoT/IoT-House.ipynb, while very thorough and detailed, don't communicate that. It's like trying to tackle a pyramid - I don't know where I should aim with a sample that large. Explain, in detail, what each of those 20% components are, how they work, and why you need them in order to build a Reaqtive application.
4. Create a clear area in the project that contains examples that are F5-runnable. I tried to do this last night and wasn't successful in getting some of the simple remoting samples up and running - and they weren't particularly easy to find either. Reorganize the project to make it easy for users to download things and kick the tires. Jupyter notebooks, while neat and interesting, aren't an effective substitute for running samples in my own toolset on my own machine - which is how most developers learn-by-doing still.

I don't mean to be overly critical - I want your project to be successful and these are the things that stopped me from being able to fully explore and understand its value.

[zhuweid]

totally agreed, I am not clear the exact scenarios to use reaqtor, and how it will help you...

[MarcDHall]

This is infuriating. When I learned about Reaqtor I thought of loads of ways it can radically change and improve specs for lots of our projects... but this repo is incomprehensible.

I mean... how do I host it?? It's a remoting framework, if I can't host it what's the point? All the presentations have a "super-easy; barely an inconvenience" vibe that doesn't hold true.

It's worrying that this was raised in May and still isn't resolved given that what's needed is actually very little compared to the docs already here.

[mwadams]

A great place to get started would be for you to enumerate the ideas you have for the very little bit of documentation needed, and we can flesh them out into a project the community could help with.

As you say, the actual mechanics are fairly simple, but the concepts can be tricky to get your head around and understanding where the discontinuities in understanding are has to come from talking to people new to the libraries.

[MarcDHall]

I expected there to be a getting started page showing how to host a reaqtor server (maybe adding persistence in part two) in a generic host with a couple of observer/observable bindings and an example of client code remotely interacting with the server. I think this would be basically everything I need.

But, having seen the samples in the repo with like 40 projects in them I’m wondering how much work has to be done to make even a helloworld server/client app, and maybe I’m really naive about how this works.

[HowardvanRooijen]

@MarcDHall Shebang would be the sample you need to show you what's required to build your own hosting environment. This sample only has "in memory" persistence providers, but they should give you a hint as to what's required implement your own, if you needed to support durable persistence etc. As you can see, there's quite a bit of code in here... but that's because Reaqtor is a framework (exactly like Rx .NET), it is not a product / application / service; it's a series of components you can use to build your own applications.

[MarcDHall]

@HowardvanRooijen Thanks for the reply! You guys are under no responsibility to provide me with anything, so I don't want to imply I'm demanding anything, but as a randomly selected dev all that sample does is tell me to come back in six months to see if someone has written a runtime of some sort.

[HowardvanRooijen]

Well, it depends if your take away is that you're waiting for someone else to build your solution for you, or whether you are going to attempt to do that yourself? If you want to play with Reaqtor and understand all the moving parts - Shebang is a great workbench for doing that, sure it's all in memory etc... but it shows what's possible. We wrote the higher level samples by pulling in the Shebang components and hosting them in a .NET Interactive notebook, but you could do the same and run it in a Console App using a Worker Service template, and hey presto, you have a hosting runtime! Is it a production ready hosting environment? Well that entirely depends on what your notion of production is, and what you're trying to achieve? Shebang.App is a Console App too.

I'm taking this approach to try and get Reaqtor running on a Wilderness Labs Meadow F7v2 Board (just as soon as it arrives). If that works (I'm hoping the increase from 32mb to 64mb of RAM will allow Reaqtor to run), I can open source that code, but it's really just the same as taking the IoT sample and hosting it in a console app (which is actually what Shebang.App does), rather than a .NET Interactive Notebook.

[HowardvanRooijen]

And if you want an example of observables / ingress etc... that's what the AisBingMapsDemo.ipynb does.