Lots of documentation gaps & pending

[atrauzzi]

I've noticed while reading over the documentation that many concepts in this library lack any practical usage or setup examples.

The biggest offenders in this space seem to be remoting, clustering and persistence. It's almost like somewhere during DI, the documentation became less important. What's written has the vibe of being "docs" but once I reach the end of each section, I realize I've only been told some vague details with no guidance on how to get a practical start in my project.

Coming to this ticket tracker, I see a lot of documentation issues, some coming up to two years old.

I'm really enjoying the little bits I've been able to piece together to get akka.net in a PoC project I'm working on. It's a total fit for me. But as I get further in, I'm starting to think about even medium term implications and how adding something like persistence, clustering and remoting might totally upend my very beginner in-process fiddling. 😆

Be it resolved that without documentation, I might show up in Gitter and ask lots of beginner questions -- Is there any room to maybe do a push on tutorials, guides, short howtos and perhaps cataloguing some better practices for those of us who come from the open source side or don't have companies willing to spring for Petabridge training?

[Aaronontheweb]

The biggest offenders in this space seem to be remoting, clustering and persistence.

We have a lot of articles on there for those areas - what could we do better there?

Be it resolved that without documentation, I might show up in Gitter and ask lots of beginner questions -- Is there any room to maybe do a push on tutorials, guides, short howtos and perhaps cataloguing some better practices for those of us who come from the open source side or don't have companies willing to spring for Petabridge training?

In the short run, some free resources we (Petabridge) created:

1. https://petabridge.com/cluster - hands-on Clustering training similar to Akka.NET Bootcamp; I haven't promoted it much on purpose, but that's worth a look.
2. https://github.com/petabridge/Cluster.WebCrawler - mode modernized version of our Akka.Cluster WebCrawler code sample that runs on .NET Core with K8s for orchestration, et al.
3. And of course, Akka.NET Bootcamp

Feel free to ask questions in the Gitter chat in the short run - we have about 1600 people in the room: https://gitter.im/akkadotnet/akka.net

But obviously, we want to improve the documentation too. Akka.NET v1.4.0 is coming out at the end of February and we'll do a pass on the documentation after that.

If it's just more examples and tutorials, we can do that - but more specifics on where you need help would help us help you.

[atrauzzi]

If it's just more examples and tutorials, we can do that - but more specifics on where you need help would help us help you.

For sure! 🙂

I think it'd be great to start with persistence as that's what I'm trying to learn my way into at the moment.

• While I love that it opens up with an "Architecture" section, I feel like I'm introduced to new types of actors before understanding just how I enable persistence in my project. It might even be that the "Architecture" section is too concrete? 😅
• Case in point... I only see *UntypedActor and have no connection back to the ReceiveActor subclasses I've been authoring up until now. Their introduction causes me to have a lot of architectural questions and doubts about my current actor structure.
• My best assumption at the moment would be that persistent actors are to somehow become parents of my existing ones? But again, I have no clear guidance on how to have a first success.
• I would move the Storage Plugins section up to be the 2nd-ish item in the list.

So, I think while there's lots of useful info here, what I - as a beginner with akka.net - would benefit most from is something that says: "You have a project that is akka.net enabled, here's a step-by-step guide to enable persistence using EF (or whatever is the most mainstream low-setup vanilla storage backend driver). Something like: Step 1 - add persistence to your project. Step 2 - configure your persistence driver. Step 3 - persistence-enable a graph of existing actors."

Hopefully this helps as a start? I'm more than happy to start asking questions in Gitter and we can take a heuristic approach to this.

[sean-gilliam]

So you're looking for more of a how-to guide? We've got plenty of documentation on the interworkings of how everything works and loads of examples, but no how-tos. That's something we've definitely dropped the ball on. Hopefully we can step up our game and provide those. Always willing to accept PRs =)

[atrauzzi]

Really, I'm not even sure large howtos are needed. Just help people with getting over that initial wiring, best practices and gotchas.

Although if we're gonna talk PRs, I think I'd be more comfortable after building some confidence 😉

[to11mtm]

I think a big help would be taking some of the samples and extracting parts of those into the docs, -especially- i/a Persistence and Clustering/Sharding.

FWIW, I started using Akka.Net back in late 2015, but haven't used the clustering/sharding bits in a couple years. I'm finding as I'm getting back into it that yes, the samples are still far more useful than the docs in that instance.

In some ways it is a bit of a contrast; the basic parts of the documentation are -amazing- at giving an introduction to the actor model and providing good docs.

Some things that might be useful to share or put in the docs:

• Code Snippets to 'auto-kill' a process once the cluster is down (This is pretty easy to do)

• A 'more complete' At-Least-Once-Delivery example. Namely, providing a decent pattern i/a Guid Correlation and/or providing an example of how to make sure the recipient only processes the message once. Yes, this is fairly trivial (and, again, can vary by use case) but some folks learn better when they can focus on just the 'hard/new' part of the problem and not get lost in the minutiae.

• Some guidance on good patterns to 'customize' your HOCON at startup in specific points. There are some very good and very bad ways to do this IIRC... Actually in general I haven't looked at the HOCON docs in a couple years but I remember wishing they were better because it's a great format and I wish it would fall into more use.

Although if we're gonna talk PRs, I think I'd be more comfortable after building some confidence 😉

One of the best things about the folks on this project is IME they -are- the sorts of people who can guide you through your PRs if they are 90% there. I did a PR a while back and @Aaronontheweb gave great feedback and guided me to make appropriate changes.

I'd help on some Doc PRs but I owe a few to another project already... ;) Maybe this summer.

[atrauzzi]

A question I came up with today might also be a good example of how the docs can be improved, beyond introductory or purely technical examples.

I'm writing this comment shortly after posing that question -- that said, I think the nature of it is architectural, but the best answers will actually be technical. Ideally by pointing to some known pattern or best practice.

What if the docs had a "common/familiar patterns and how to achieve them using akka.net" section?