Akka.NET Documentation Improvement Proposal

[eaba]

[WIP] Fix fragemented documentations

Add Getting Started section

• [ ] https://github.com/akkadotnet/akka.net/pull/5500
• [x] Create ~/articles/intro/getting-started
• [x] Create ~/articles/intro/getting-started/tutorial-overview.md this will describe everything about the application to be built to serve as as hook for the user.
• [x] Move ~/articles/intro/tutorial-1.md --> ~/articles/intro/getting-started/tutorial-1.md
• [x] Move ~/articles/intro/tutorial-2.md --> ~/articles/intro/getting-started/tutorial-2.md
• [x] Move ~/articles/intro/tutorial-3.md --> ~/articles/intro/getting-started/tutorial-3.md
• [x] Move ~/articles/intro/tutorial-4.md --> ~/articles/intro/getting-started/tutorial-4.md

Reorganize Configuration

• [x] Move ~/articles/hocon/index.md --> ~/articles/configuration/hocon.md
• [x] Add ~/articles/configuration/index.md - new page that explains how configuration works in Akka.NET, best practices, links to bootcamp section on fallbacks.
• [x] Move ~/articles/configuration/* (all of the module-specific configurations) --> ~/articles/configuration/modules/*
• [x] Create ~/articles/deployment (all of the deployment scenarios) --> ~~/articles/deployment/*

I think we should do it this way so all of the configuration pages fall under a single area. The configs for each module will be kept in the same area as where we explain conceptually how config works, how HOCON works, and best practices for using it.

Update UntypedActor to ReceiveActor

• [ ] ~/articles/actors/fault-tolerance.md
• [ ] revise ~/articles/actors/untyped-actor-api.md

Improve Getting Started Guide

• [ ] Rename ~/articles/intro to ~/articles/getting-started-guide
• [ ] Rename ~/articles/intro/what-is-akka.md to ~/articles/getting-started-guide/introduction-to-akka.md and update content
• [ ] Split ~/articles/intro/what-problems-does-actor-model-solve.md into ~/articles/getting-started-guide/why-modern-systems-need-a-new-programming-model.md and ~/articles/getting-started-guide/how-the-actor-model-meets-the-needs-of-modern-distributed-systems.md, and update content where necessary.
• [ ] Add a link for downloading code sample

Update Actor - add more sections

• [ ] Create ~/articles/actors/Introduction/Actors.md
• [ ] Create ~/articles/actors/Introduction/creating-actors.md
• [ ] Create ~/articles/actors/Introduction/actor-api.md
• [ ] Create ~/articles/actors/Introduction/actor-api.md
• [ ] Create ~/articles/actors/Introduction/identitying-actors-via-actor-selection.md
• [ ] Create ~/articles/actors/Introduction/messages-and-immutability.md
• [ ] Create ~/articles/actors/Introduction/send-messages.md
• [ ] Create ~/articles/actors/Introduction/receive-messages.md
• [ ] Create ~/articles/actors/Introduction/reply-to-messages.md
• [ ] Create ~/articles/actors/Introduction/receive-timeout.md
• [ ] Create ~/articles/actors/Introduction/timers-scheduled-messages.md
• [ ] Create ~/articles/actors/Introduction/stopping-actors.md
• [ ] Create ~/articles/actors/Introduction/become-unbecome.md
• [ ] Create ~/articles/actors/Introduction/stash.md
• [ ] Create ~/articles/actors/Introduction/extending-actors.md
• [ ] Create ~/articles/actors/Introduction/initialization-pattern.md

[Aaronontheweb]

Reorganize Configuration

• [ ] Move ~/articles/hocon/index.html --> ~/articles/configuration/hocon.html
• [ ] Add ~/articles/configuration.index.html - new page that explains how configuration works in Akka.NET, best practices, links to bootcamp section on fallbacks.
• [ ] Move ~/articles/configuration/* (all of the module-specific configurations) --> ~/articles/configuration/modules/*

I think we should do it this way so all of the configuration pages fall under a single area. The configs for each module will be kept in the same area as where we explain conceptually how config works, how HOCON works, and best practices for using it.

[Aaronontheweb]

Moving the sample app into its own directory is a good idea, but I would keep the "intro" area and not rename it (less work, does basically the same thing.)

I also really like the idea of having an app overview page.

[Aaronontheweb]

So instead of moving things around, we can create ~/articles-2 where all changes will be applied. We could have Documenation 2 so that we can get users feedback on the new layout.

I'd bypass this - users realistically aren't going to give us that much feedback on it. We're better off reorganizing what we have / know can be improved and filling in the gaps with the numerous documentation issues that are spelled out in this repository.

[eaba]

@Aaronontheweb What about having the sample apps inside getting started folder? I have updated the spec to reflect this!

[Aaronontheweb]

@eaba I'd also keep those in the intro folder

[eaba]

@Aaronontheweb The intro folder should house the getting started folder? I have updated the spec to reflect this.

[Aaronontheweb]

 Create ~/articles/intro/getting-started
 Create ~/articles/intro/getting-started/over-view.md this will describe everything about the application to be built to serve as as hook for the user.

This looks a little different than we had discussed during the call - all I mean is that the tutorial needs to be ring-fenced into its own area separate from the other intro materials. It's still a really great idea to have a separate "what do you need to get started?" page that belongs in the intro area.

[Aaronontheweb]

https://www.reddit.com/r/dotnet/comments/sa3dcb/actor_frameworks/?utm_source=share&utm_medium=ios_app&utm_name=iossmf - some criticisms about our documentation which are pretty valid. Some of the examples are dated and old. We need to open checklist items on this issue or sub-issues to flag those samples for modernization and bring them into compliance with our Documentation Guidelines.

[sean-gilliam]

Once again, let me apologize for sprinkling those TBD comments in the code. It was originally meant as an impetus for developers to flesh out the docs. While a lot of them have been knocked out, there's obviously a ton more that hasn't.

I haven't really had the time to get back into this project. Hopefully this year will be less chaotic than the last few, and I can dig back into it.

[Aaronontheweb]

@sean-gilliam not a problem at all Sean - we would appreciate any help you have to offer.