Making docs better (#29623)

Co-authored-by: Arnout Engelen <github@bzzt.net>

akka-docs/src/main/paradox/stream/operators/ActorFlow/ask.md

@@ -1,6 +1,6 @@
 # ActorFlow.ask
 
-Use the "Ask Pattern" to send each stream element as an `ask` to the target actor (of the new actors API), and expect a reply back that will be emitted downstream.
+Use the "Ask Pattern" to send each stream element as an `ask` to the target actor (of the new actors API), and expect a reply that will be emitted downstream.
 
 @ref[Actor interop operators](../index.md#actor-interop-operators)
 
@@ -28,8 +28,8 @@ If any of the asks times out it will fail the stream with an @apidoc[AskTimeoutE
 The `ask` operator requires
 
 * the actor `ref`,
-* a `makeMessage` function to create the message sent to the actor from the incoming element and the actor ref accepting the actor's reply message,
-* and a timeout.
+* a `makeMessage` function to create the message sent to the actor from the incoming element, and the actor ref accepting the actor's reply message 
+* a timeout.
 
 See also:
 
@@ -37,7 +37,7 @@ See also:
 
 ## Examples
 
-The `ActorFlow.ask` sends a message to the actor which expects `Asking` messages which contain the actor ref for replies of type `Reply`. The replies are emitted when received and the `map` extracts the message `String`.
+The `ActorFlow.ask` sends a message to the actor. The actor expects `Asking` messages which contain the actor ref for replies of type `Reply`. When the actor for replies receives a reply, the `ActorFlow.ask` stream stage emits the reply and the `map` extracts the message `String`.
 
 Scala
 :  @@snip [ask.scala](/akka-stream-typed/src/test/scala/docs/scaladsl/ActorFlowSpec.scala) { #imports #ask-actor #ask }
@@ -56,7 +56,7 @@ Java
 
 **completes** when upstream completes and all futures have been completed and all elements have been emitted
 
-**fails** when the passed in actor terminates, or a timeout is exceeded in any of the asks performed
+**fails** when the passed-in actor terminates, or when any of the `ask`s exceed a timeout
 
 **cancels** when downstream cancels
 

akka-docs/src/main/paradox/stream/operators/ActorSink/actorRef.md

@@ -24,11 +24,11 @@ This operator is included in:
 
 Sends the elements of the stream to the given `ActorRef`.
 If the target actor terminates the stream will be canceled.
-When the stream is completed successfully the given `onCompleteMessage`
+When the stream completes successfully the given `onCompleteMessage`
 will be sent to the destination actor.
-When the stream is completed with failure a the throwable that was signaled
-to the stream is adapted to the Actors protocol using `onFailureMessage` and
-then then sent to the destination actor.
+When the stream completes with failure the throwable that was signaled
+to the stream is adapted to the Actor's protocol using `onFailureMessage` and
+then sent to the destination actor.
 
 It will request at most `maxInputBufferSize` number of elements from
 upstream, but there is no back-pressure signal from the destination actor,

akka-docs/src/main/paradox/stream/operators/ActorSink/actorRefWithBackpressure.md

@@ -47,4 +47,3 @@ Java
 **backpressures** when the actor acknowledgement has not arrived
 
 @@@
-

akka-docs/src/main/paradox/stream/operators/ActorSource/actorRefWithBackpressure.md

@@ -34,7 +34,10 @@ See also:
 
 ## Example
 
-With `actorRefWithBackpressure` two actors get into play: one which feeds the stream and is materialized when the stream runs, and one which is provided by us and gets the ack signal when an element is emitted into the stream.
+With `actorRefWithBackpressure` two actors get into play: 
+
+1. An actor that is materialized when the stream runs. It feeds the stream.
+2. An actor provided by the user. It gets the ack signal when an element is emitted into the stream.
 
 For the ack signal we create an @scala[`Emitted` object]@java[empty `Emitted` class].
 
@@ -53,7 +56,7 @@ Java
 
 @@@div { .callout }
 
-**emits** when there is demand and a message is sent to the materialized @scala[`ActorRef[T]`]@java[`ActorRef<T>`]
+**emits** when a message is sent to the materialized @scala[`ActorRef[T]`]@java[`ActorRef<T>`] it is emitted as soon as there is demand from downstream
 
 **completes** when the passed completion matcher returns a `CompletionStrategy`
 

akka-docs/src/main/paradox/stream/operators/index.md

@@ -324,7 +324,7 @@ Operators meant for inter-operating between Akka Streams and Actors:
 |ActorSource|<a name="actorrefwithbackpressure"></a>@ref[actorRefWithBackpressure](ActorSource/actorRefWithBackpressure.md)|Materialize an @java[`ActorRef<T>`]@scala[`ActorRef[T]`] of the new actors API; sending messages to it will emit them on the stream. The source acknowledges reception after emitting a message, to provide back pressure from the source.|
 |ActorSink|<a name="actorrefwithbackpressure"></a>@ref[actorRefWithBackpressure](ActorSink/actorRefWithBackpressure.md)|Sends the elements of the stream to the given @java[`ActorRef<T>`]@scala[`ActorRef[T]`] of the new actors API with backpressure, to be able to signal demand when the actor is ready to receive more elements.|
 |Source/Flow|<a name="ask"></a>@ref[ask](Source-or-Flow/ask.md)|Use the "Ask Pattern" to send a request-reply message to the target `ref` actor (of the classic actors API).|
-|ActorFlow|<a name="ask"></a>@ref[ask](ActorFlow/ask.md)|Use the "Ask Pattern" to send each stream element as an `ask` to the target actor (of the new actors API), and expect a reply back that will be emitted downstream.|
+|ActorFlow|<a name="ask"></a>@ref[ask](ActorFlow/ask.md)|Use the "Ask Pattern" to send each stream element as an `ask` to the target actor (of the new actors API), and expect a reply that will be emitted downstream.|
 |Source/Flow|<a name="watch"></a>@ref[watch](Source-or-Flow/watch.md)|Watch a specific `ActorRef` and signal a failure downstream once the actor terminates.|
 
 ## Compression operators