Tidied up the language on Fault Tolerance page (#7232)

* wip - Update fault-tolerance.md

* Update fault-tolerance.md

* Update fault-tolerance.md

typo

* Update fault-tolerance.md

trailing spaces

---------

Co-authored-by: Aaron Stannard <[email protected]>

Author: sctmike

docs/articles/actors/fault-tolerance.md

@@ -4,25 +4,16 @@ title: Fault tolerance
 ---
 # Fault Tolerance
 
-As explained in [Actor Systems](xref:actor-systems) each actor is the supervisor of its
-children, and as such each actor defines fault handling supervisor strategy.
-This strategy cannot be changed afterwards as it is an integral part of the
-actor system's structure.
+As explained in [Actor Systems](xref:actor-systems), each actor is the supervisor of its
+children, and as such each actor defines a fault handling supervisor strategy.
+This strategy cannot be changed after a child actor is created.
 
 ## Fault Handling in Practice
 
-First, let us look at a sample that illustrates one way to handle data store errors,
-which is a typical source of failure in real world applications. Of course it depends
-on the actual application what is possible to do when the data store is unavailable,
-but in this sample we use a best effort re-connect approach.
+Let's set up an example strategy which will handle data store errors in a child actor. In this sample we use a best effort re-connect approach.
 
 ## Creating a Supervisor Strategy
 
-The following sections explain the fault handling mechanism and alternatives
-in more depth.
-
-For the sake of demonstration let us consider the following strategy:
-
 ```csharp
 protected override SupervisorStrategy SupervisorStrategy()
 {
@@ -46,9 +37,7 @@ protected override SupervisorStrategy SupervisorStrategy()
 }
 ```
 
-I have chosen a few well-known exception types in order to demonstrate the application of the fault handling directives described in [Supervision and Monitoring](xref:supervision). First off, it is a one-for-one strategy, meaning that each child is treated separately (an all-for-one strategy works very similarly, the only difference is that any decision is applied to all children of the supervisor, not only the failing one). There are limits set on the restart frequency, namely maximum 10 restarts per minute; each of these settings could be left out, which means that the respective limit does not apply, leaving the possibility to specify an absolute upper limit on the restarts or to make the restarts work infinitely. The child actor is stopped if the limit is exceeded.
-
-This is the piece which maps child failure types to their corresponding directives.
+We will handle a few exception types to demonstrate some fault handling directives described in [Supervision and Monitoring](xref:supervision). This strategy is "one-for-one", meaning that each child is treated separately. The alternative is an "all-for-one" strategy, where a decision is applied to _all_ children of the supervisor, not only the failing one. We have chosen to set a limit of maximum 10 restarts per minute; The child actor is stopped if the limit is exceeded. We could have chosen to leave this argument out, which would have created a strategy where the child actor would restart indefinitely.
 
 > [!NOTE]
 > If the strategy is declared inside the supervising actor (as opposed to
@@ -65,10 +54,7 @@ exceptions are handled by default:
 * `ActorKilledException` will stop the failing child actor; and
 * Any other type of `Exception` will restart the failing child actor.
 
-If the exception escalate all the way up to the root guardian it will handle it
-in the same way as the default strategy defined above.
-
-You can combine your own strategy with the default strategy:
+You can combine your own strategy with the default strategy like this:
 
 ```csharp
 protected override SupervisorStrategy SupervisorStrategy()
@@ -90,7 +76,7 @@ protected override SupervisorStrategy SupervisorStrategy()
 
 ### Stopping Supervisor Strategy
 
-Closer to the Erlang way is the strategy to just stop children when they fail
+An alternative which is closer to the Erlang way is to stop children when they fail
 and then take corrective action in the supervisor when DeathWatch signals the
 loss of the child. This strategy is also provided pre-packaged as
 `SupervisorStrategy.StoppingStrategy` with an accompanying
@@ -99,17 +85,13 @@ loss of the child. This strategy is also provided pre-packaged as
 
 ### Logging of Actor Failures
 
-By default the `SupervisorStrategy` logs failures unless they are escalated.
-Escalated failures are supposed to be handled, and potentially logged, at a level
-higher in the hierarchy.
-
-You can mute the default logging of a `SupervisorStrategy` by setting
+The default strategy logs failures unless they are escalated. You can mute the default logging of a `SupervisorStrategy` by setting
 `loggingEnabled` to `false` when instantiating it. Customized logging
 can be done inside the `Decider`. Note that the reference to the currently
 failed child is available as the `Sender` when the `SupervisorStrategy` is
 declared inside the supervising actor.
 
-You may also customize the logging in your own ``SupervisorStrategy`` implementation
+You can also customize the logging in your own ``SupervisorStrategy`` implementation
 by overriding the `logFailure` method.
 
 ## Supervision of Top-Level Actors
@@ -121,8 +103,7 @@ strategy.
 
 ## Test Application
 
-The following section shows the effects of the different directives in practice,
-wherefor a test setup is needed. First off, we need a suitable supervisor:
+Consider this custom `SupervisorStrategy`:
 
 ```csharp
 public class Supervisor : UntypedActor
@@ -159,7 +140,7 @@ public class Supervisor : UntypedActor
 }
 ```
 
-This supervisor will be used to create a child, with which we can experiment:
+This supervisor will be used to create a child actor:
 
 ```csharp
 public class Child : UntypedActor
@@ -184,9 +165,9 @@ public class Child : UntypedActor
 }
 ```
 
-The test is easier by using the utilities described in [Akka-Testkit](xref:testing-actor-systems).
+We'll use the utilities in [Akka-Testkit](xref:testing-actor-systems) to help us describe and test the expected behavior.
 
-Let us create actors:
+First, we'll create actors:
 
 ```csharp
 var supervisor = system.ActorOf<Supervisor>("supervisor");
@@ -195,8 +176,7 @@ supervisor.Tell(Props.Create<Child>());
 var child = ExpectMsg<IActorRef>(); // retrieve answer from TestKit’s TestActor
 ```
 
-The first test shall demonstrate the `Resume` directive, so we try it out by
-setting some non-initial state in the actor and have it fail:
+Our first test will demonstrate `Directive.Resume`, so we set some non-initial state in the child actor and cause it to fail:
 
 ```csharp
 child.Tell(42); // set state to 42
@@ -208,30 +188,27 @@ child.Tell("get");
 ExpectMsg(42);
 ```
 
-As you can see the value 42 survives the fault handling directive because we're using the `Resume` directive, which does not cause the actor to restart. Now, if we
-change the failure to a more serious `NullReferenceException`, that will no
-longer be the case:
+As you can see the value 42 survives the fault handling directive because we're using the `Resume` directive, which does not cause the actor to restart.
+
+If we change the failure to a more serious `NullReferenceException`, which we defined above to result in a `Restart` directive, that will no longer be the case:
 
 ```csharp
 child.Tell(new NullReferenceException());
 child.Tell("get");
 ExpectMsg(0);
 ```
 
-This is because the actor has restarted and the original `Child` actor instance that was processing messages will be destroyed and replaced by a brand-new instance defined using the original `Props` passed to its parent.
+This is because the actor has restarted and the original `Child` actor instance that was processing messages will be destroyed and replaced by a brand-new instance defined using the same `Props`.
 
-And finally in case of the fatal `IllegalArgumentException` the child will be
-terminated by the supervisor:
+And finally in case of the fatal `ArgumentException`, our strategy will return a stop directive, and the child will be terminated by the supervisor:
 
 ```csharp
 Watch(child); // have testActor watch "child"
 child.Tell(new ArgumentException()); // break it
 ExpectMsg<Terminated>().ActorRef.Should().Be(child);
 ```
 
-Up to now the supervisor was completely unaffected by the child's failure,
-because the directives set did handle it. In case of an `Exception`, this is not
-true anymore and the supervisor escalates the failure.
+Up to now the supervisor was completely unaffected by the child's failure, because the directives in our strategy handled the exception. However, if we cause an `Exception`, none of our handlers are invoked and the supervisor escalates the failure.
 
 ```csharp
 supervisor.Tell(Props.Create<Child>()); // create new child
@@ -247,14 +224,12 @@ message.ExistenceConfirmed.Should().BeTrue();
 ```
 
 The supervisor itself is supervised by the top-level actor provided by the
-`ActorSystem`, which has the default policy to restart in case of all
-`Exception` cases (with the notable exceptions of
-`ActorInitializationException` and `ActorKilledException`). Since the
-default directive in case of a restart is to kill all children, we expected our poor
-child not to survive this failure.
+`ActorSystem`. This has the default policy to restart as a result of all
+`Exception`s except `ActorInitializationException` and `ActorKilledException`. Since the
+default directive in case of a restart is to kill all children, our poor
+child did not survive this failure.
 
-In case this is not desired (which depends on the use case), we need to use a
-different supervisor which overrides this behavior.
+If we don't want our children to be restarted we can override `PreRestart` in the Supervisor:
 
 ```csharp
 public class Supervisor2 : UntypedActor
@@ -296,7 +271,7 @@ public class Supervisor2 : UntypedActor
 ```
 
 With this parent, the child survives the escalated restart, as demonstrated in
-the last test:
+this last test:
 
 ```csharp
 var supervisor2 = system.ActorOf<Supervisor2>("supervisor2");