Reorganization of Akka.NET docs for v1

[Aaronontheweb]

Took me forever to put this together, but here it is - my proposed rework for the Akka.NET docs for v1.0.

Documentation Guidelines

Here are some rules and guidelines to follow when working on the updated docs.

• Use the v1.0 APIs everywhere, since they will be supported long-term. We just published a pre-release V1 nuget package to make this easier for writing compilable samples.
• Replace any Java / Scala code from existing documents with relevant C# and F# samples.
• Use .NET Fiddle for any runnable samples in the docs.
• Include BOTH F# and C# samples - if you need help with the F#, let @akkadotnet/fsharpteam know.
• Draw diagrams where appropriate. Most programmers are visual learners. They will love you for this.

All of the docs are written in Markdown format and are saved to the /wiki directory in this repo.

This will take a lot of effort, so we need all the help we can get. Calling all @akkadotnet/contributors - pick some areas where you can help and send us some PRs for the documents there.

---

Akka.NET v1.0 Documentation

This is what the table of contents will look like - all left-most items are individual pages. Anything that's indented further in can either be a section on that page or its own sub-page depending on whether or not the content is something that should be immediately visible to developers scanning the TOC.

Introduction

• [ ] What is Akka.NET?
  • [ ] Akka & Typesafe
• [ ] Why Akka.NET?
• [ ] Akka.NET Quickstart
  • [ ] C# Quickstart
  • [ ] F# Quickstart
• [ ] What are some real-world use cases for Akka.NET?
• [ ] FAQ
  • [ ] Mono Support
  • [ ] Remoting & Clustering
  • [ ] Contributing
  • [ ] Commercial Support
• [ ] Learning Resources
  • [ ] Akka.NET Bootcamp
  • [ ] OSS Akka.NET Examples
  • [ ] Videos
  • [ ] Blogs & Articles
  • [ ] Podcasts & Interviews
  • [ ] Talks and Presentations

    Akka.NET Concepts and Terminology

• [ ] Terminology, Concepts
• [ ] Actor Systems
• [ ] What is an Actor?
• [ ] What is a Message?
  • [ ] Immutability
• [ ] Supervision and Monitoring
• [ ] Actor References, Paths, and Addresses
• [ ] Location Transparency
• [ ] Message Delivery Reliability
• [ ] Configuration

  Working with Actors

• [ ] Creating your first Actor
  • [ ] C#
  • [ ] F#
• [ ] Defining an Actor class
  • [ ] ReceiveActor
  • [ ] UntypedActor
• [ ] What's in an actor?
  • [ ] State
  • [ ] Behavior(s)
  • [ ] Mailbox
  • [ ] Children
  • [ ] Supervisor Strategy
  • [ ] Context
• [ ] ActorRefs and ActorSelections
  • [ ] Location Transparency
  • [ ] Explan how actors can be restarted independently of actorrefs, and this is why they're cool
• [ ] Creating actors with Props
  • [ ] Props
  • [ ] What's the point?
  • [ ] Serializability
  • [ ] Role in restarts
  • [ ] System.ActorOf
  • [ ] Creating Children with Context.ActorOf
• [ ] Handling Messages
  • [ ] ReceiveActor
  • [ ] UntypedActor
  • [ ] if, else if, else - type interference
  • [ ] PatternMatch
• [ ] Sending Messages
  • [ ] Immutability
  • [ ] Tell
  • [ ] Ask
  • [ ] Forward
  • [ ] Replying to messages
• [ ] Looking up Actors
  • [ ] ActorSelection
• [ ] Stopping Actors
  • [ ] PoisonPill
  • [ ] Graceful Stop
• [ ] What happens when an actor dies?
  • [ ] Unplanned Termination ("Crashes")
  • [ ] Supervision strategies in action
  • [ ] Restarts
  • [ ] What happens to messages during restarts?
    • [ ] Unprocessed messages
    • [ ] Message that caused the restart
  • [ ] What happens to children during restarts?
  • [ ] Planned Termination
  • [ ] How to stop an actor
  • [ ] DeathWatch
    • [ ] What happens to messages during termination?
    • [ ] Unprocessed messages
    • [ ] Message that caused the restart
  • [ ] What happens to children after termination?
• [ ] The Actor Lifecycle
  • [ ] PreStart
  • [ ] PreRestart
  • [ ] PostStop
  • [ ] PostRestart
  • [ ] DeathWatch
• [ ] Dispatchers
  • [ ] What Dispatchers Do
  • [ ] Types of Dispatchers
  • [ ] ThreadPoolDispatcher (default)
  • [ ] ForkJoinDispatcher
  • [ ] SynchronizedDispatcher
  • [ ] SingleThreadDispatcher
  • [ ] TaskDispatcher
  • [ ] Custom Dispatchers
• [ ] Mailboxes
  • [ ] What Mailboxes Do
  • [ ] Types of Mailboxes
  • [ ] UnboundedMailbox (default)
  • [ ] PriorityMailbox
  • [ ] Custom Mailboxes
• [ ] Switchable Behaviors
  • [ ] Become
  • [ ] BecomeStacked
  • [ ] UnbecomeStacked
• [ ] Stashing Messages
  • [ ] Bounded Stash
  • [ ] Unbounded Stash
• [ ] Detecting Failures with ReceiveTimeout
• [ ] Dependency Injection and Actors
  • [ ] Ninject
  • [ ] Autofac
  • [ ] Castle Windsor
• [ ] Routers
  • [ ] Pool vs. Group
  • [ ] Supervision
  • [ ] RoundRobin
  • [ ] Broadcast
  • [ ] Random
  • [ ] ConsistentHash
  • [ ] TailChopping
  • [ ] SmallestMailbox

    Configuration

• [ ] Using Akka.NET Config (HOCON) in Production
  • [ ] Fallbacks
  • [ ] App.config & Web.config
  • [ ] Parsing Configuration from Strings
• [ ] Configuring Akka.NET Modules
  • [ ] Akka.Remote
  • [ ] Akka.Cluster
  • [ ] Akka.Persistence
• [ ] Configuring Loggers
  • [ ] Logging Options
  • [ ] Serilog
  • [ ] NLog
  • [ ] Custom Loggers

    ActorSystems & Utilities

• [ ] Finite State Machines (FSM)
• [ ] EventBus
• [ ] Scheduler
  • [ ] Scheduling Recurring Messages
  • [ ] Canceling a Recurring Message
  • [ ] Scheduling a One-time Message
• [ ] Inbox
• [ ] ActorSystem Extensions
  • [ ] Using ActorSystem Extensions
  • [ ] Creating ActorSystem Extensions
• [ ] Extending the Actor Construction Pipeline
  • [ ] What does the Actor Construction Pipeline do?
  • [ ] Use Cases
  • [ ] Examples

    Unit Testing Your Actors

• [ ] Using Akka.TestKit
  • [ ] With XUnit
  • [ ] With MSTest
• [ ] Writing Testable Actors
• [ ] TestKit Tools
  • [ ] TestActor
  • [ ] Expecting Messages
  • [ ] TestProbe
  • [ ] EventFilter

    Akka.Remote (Networked ActorSystems)

• [ ] Remoting Overview
  • [ ] Remote Addressing
  • [ ] How Remote Connections Form
  • [ ] Transports
  • [ ] Location Transparency
• [ ] Serialization
• [ ] Transports
  • [ ] Helios
  • [ ] TCP
  • [ ] UDP (in the future)
  • [ ] Custom Transports
• [ ] Sending Messages to Remote Actors
  • [ ] What happens when a connection dies?
• [ ] Deploying Actors onto Remote Systems
  • [ ] What happens to remotely deployed actors when a connection dies?
  • [ ] Remote DeathWatch
• [ ] Remoting Configuration

  Akka.Cluster (Clustered ActorSystems)

• [ ] Clustering Overview
  • [ ] How is Clustering different from Remoting?
  • [ ] How a Cluster Forms
  • [ ] Seed Nodes
  • [ ] Gossip
  • [ ] Leader Election
  • [ ] Reachability
  • [ ] Location Transparency
• [ ] Cluster Routing
  • [ ] Deploying Clustered Routees
  • [ ] Configured Cluster Routers
• [ ] Cluster ActorSystem Extension
  • [ ] Getting Cluster State
  • [ ] Subscribing to Cluster Events
  • [ ] Cluster Event Types
  • [ ] Reachability
  • [ ] MemberUp / MemberDown
• [ ] Cluster Configuration

  Akka.Persistence (Guaranteed Message Delivery, Persistent Actors)

• [ ] Persistence Overview
  • [ ] Goals of Persistence
  • [ ] Snapshots
  • [ ] Journals
  • [ ] Persistence Plugins
  • [ ] SQL Server
  • [ ] File System
• [ ] Guaranteed Delivery of Messages
• [ ] Creating your own Persistent Actors
• [ ] Creating your own Persistence Target
• [ ] Persistence Configuration

  Information for Akka Developers

• [ ] Building and Distributing Akka.NET
• [ ] Contributor guidelines
• [ ] Documentation Guidelines
• [ ] Team

  Project Information

• [ ] Licenses
• [ ] Sponsors
• [ ] Project

  Additional Information

• [ ] FAQ
• [ ] Online resources
• [ ] Books
• [ ] Commercial Support & Training

[Aaronontheweb]

BTW - please feel free to use any of the diagrams or language in Akka.NET Bootcamp for writing these sections. All of that stuff is licensed under Apache 2.0.

Just need a copyright reference back to the original source of the content and it's good to go.

[Aaronontheweb]

If you have a section that you want to write, please call it out on this thread and we'll mark it as "claimed."

[Aaronontheweb]

I will take the following from Working with Actors

• [X] Creating your first Actor
  • [X] C#
  • [X] F#
• [X] Defining an Actor class
  • [X] ReceiveActor
  • [X] UntypedActor
• [X] What's in an actor?
  • [X] State
  • [X] Behavior(s)
  • [X] Mailbox
  • [x] Children
  • [X] Supervisor Strategy
  • [X] Context
• [X] ActorRefs and ActorSelections
  • [X] Location Transparency
  • [X] Explan how actors can be restarted independently of actorrefs, and this is why they're cool
• [X] Creating actors with Props
  • [X] Props
  • [X] What's the point?
  • [X] Serializability
  • [X] Role in restarts
  • [X] System.ActorOf
  • [X] Creating Children with Context.ActorOf
• [X] Handling Messages
  • [X] ReceiveActor
  • [X] UntypedActor
  • [X] if, else if, else - type interference
  • [X] PatternMatch
• [X] Sending Messages
  • [X] Immutability
  • [X] Tell
  • [X] Ask
  • [X] Forward
  • [X] Replying to messages

[rogeralsing]

Looks great!

Are we missing a deployment/hosting section?

Asp.NET Console Apps TopShelf etc.

[Aaronontheweb]

@rogeralsing yeah, that should be its own section IMHO - just as important as configuration. Might also want to include bits about integrating Akka.NET with technologies like Azure EventHub, NServiceBus, etc... in that area

[rogeralsing]

And just to be super anal here: We do have a graphical profile, colors, look n feel etc. which I really want us to stick to in terms of diagrams etc.

So please go easy on the gradients and dropshadows ;-)

[Aaronontheweb]

So please go easy on the gradients and dropshadows ;-)

I'm going to go nuts with the animated GIFs... Just sayin ;)

[Aaronontheweb]

Forgot - we need a section on AsyncAwait support inside Actors and TPL + PipeTo

[rogeralsing]

I dont mind animated gifs, but if they are too ugly, Im going bananas in PPT ;-)

[rogeralsing]

Maybe a section on patterns?

Scatter Gather (not the router but the concept) Reliable Proxy Circuitbreaker

http://doc.akka.io/docs/akka/snapshot/scala/howto.html

[stefansedich]

Would patterns fit better into a separate repo. Have all the samples as part of a solution and document them as readme.md in github. I find things like patterns I prefer code I can open up and play with while reading the doco.

Cheers On 4 Apr 2015 9:16 am, "Roger Alsing" notifications@github.com wrote:

Maybe a section on patterns?

Scatter Gather (not the router but the concept) Reliable Proxy Circuitbreaker

http://doc.akka.io/docs/akka/snapshot/scala/howto.html

— Reply to this email directly or view it on GitHub https://github.com/akkadotnet/akka.net/issues/794#issuecomment-89478716.

[mmisztal1980]

Wilk do :)

-----Wiadomość oryginalna----- Od: "Aaron Stannard" notifications@github.com Wysłano: ‎2015-‎04-‎04 01:26 Do: "akkadotnet/akka.net" akka.net@noreply.github.com DW: "Maciek Misztal" mmisztal1980@gmail.com Temat: Re: [akka.net] Reorganization of Akka.NET docs for v1 (#794)

If you have a section that you want to write, please call it out on this thread and we'll mark it as "claimed." — Reply to this email directly or view it on GitHub.

[Horusiath]

I'll guest I'll take whole Persistence paragraph. Then I'll see what's next.

PS: Don't you think, that for the case of C#/F#code samples we should present them in tab view (just like msdn does)?

[rogeralsing]

@Horusiath, maybe, but i the msdn case, it's the same classes/methods beeíng described. In our case, the F# API has functons that are not the same as the C# oop api, maybe that would be confusing ?

[Aaronontheweb]

@Horusiath i was thinking just show one on top of the other for now - not sure how to do the tabbed view with our existing CSS / markdown

[rogeralsing]

I think it would be possible at least for the DotNetFiddler stuff, they have an advanced widget builder that allows this.

Then the widget could be inserted as a normal iframe in the markdown.

[Aaronontheweb]

Please refer to https://github.com/akkadotnet/getakka.net/issues/7 going forward for this issue.