fix: Fact-check of streams, server events, and backward compatibility

docs/06-concepts/15-streams.md

@@ -1,3 +1,7 @@
+---
+description: Stream data between server and client in Serverpod using streaming methods over a self-managed WebSocket connection, with support for bidirectional streams and serializable exceptions.
+---
+
 # Streams
 
 For some applications, it's not enough to be able to call server-side methods. You may also want to push data from the server to the client or send data two-way. Examples include real-time games or chat applications. Luckily, Serverpod supports a framework for streaming data. It's possible to stream any serialized objects to or from any endpoint.
@@ -53,7 +57,7 @@ In the example above, the `echoStream` method passes back any message sent throu
 
 :::tip
 
-Note that we can mix different types in the stream. This stream is defined as dynamic and can contain any type that can be serialized by Serverpod.
+The stream is defined as dynamic and can contain any type that can be serialized by Serverpod.
 
 :::
 
@@ -75,7 +79,7 @@ All streams in parameters are closed when the method call is over.
 
 Authentication is seamlessly integrated into streaming method calls. When a client initiates a streaming method, the server automatically authenticates the session.
 
-Authentication is validated when the stream is first established, utilizing the authentication data stored in the `Session` object. If a user's authentication is subsequently revoked—requiring denial of access to the stream—the stream will be promptly closed, and an exception will be thrown.
+Authentication is validated when the stream is first established, using the authentication data stored in the `Session` object. If a user's authentication is revoked, the stream is closed and an exception is thrown.
 
 For more details on handling revoked authentication, refer to the section on [handling revoked authentication](authentication/custom-overrides#handling-revoked-authentication).
 
@@ -144,7 +148,7 @@ To send a message to a client, call the `sendStreamMessage` method. You will nee
 
 #### The user object
 
-It's often handy to associate a state together with a streaming session. Typically, you do this when a stream is opened.
+Associate state with a streaming session by setting a user object when the stream is opened.
 
 ```dart
 Future<void> streamOpened(StreamingSession session) async {
@@ -156,11 +160,10 @@ You can access the user object at any time by calling the `getUserObject` method
 
 ### Handling streams in your app
 
-Before you can access streams in your client, you need to connect to the server's web socket. You do this by calling connectWebSocket on your client.
+Before you can access streams in your client, you need to connect to the server's web socket by calling `openStreamingConnection` on your client.
 
 ```dart
 await client.openStreamingConnection();
-
 ```
 
 You can monitor the state of the connection by adding a listener to the client.

docs/06-concepts/16-server-events.md

@@ -1,3 +1,7 @@
+---
+description: Use Serverpod's built-in event messaging system to send and receive messages within or across servers, coordinating streams and shared state via channels.
+---
+
 # Server events
 
 Serverpod framework comes with a built-in event messaging system. This enables efficient message exchange within and across servers, making it ideal for scenarios where shared state is needed, such as coordinating streams or managing data across a server cluster.
@@ -25,7 +29,7 @@ var message = UserUpdate(); // Model that represents changes to user data.
 session.messages.postMessage('user_updates', message);
 ```
 
-In the example above, the message published on the `user_updates` channel. Any subscriber to this channel in the server will receive the message.
+In the example above, the message is published on the `user_updates` channel. Any subscriber to this channel in the server will receive the message.
 
 ### Global messages
 
@@ -46,7 +50,7 @@ If Redis is not enabled, sending global messages will throw an exception.
 
 ## Receiving messages
 
-Receiving messages is just as simple as sending them! Serverpod provides two ways to handle incoming messages: by creating a stream that subscribes to a channel or by adding a listener to a channel.
+Serverpod provides two ways to handle incoming messages: by creating a stream that subscribes to a channel or by adding a listener to a channel.
 
 ### Creating a stream
 
@@ -59,11 +63,11 @@ stream.listen((message) {
 })
 ```
 
-In the above example, a stream is created that listens to the `user_updates` channel and processes incoming requests.
+In the above example, a stream is created that listens to the `user_updates` channel and processes incoming messages.
 
 #### Stream lifecycle
 
-The stream is automatically closed when the session is closed. If you want to close the stream manually, you simply cancel the stream subscription.
+The stream is automatically closed when the session is closed. To close the stream manually, cancel the stream subscription.
 
 ```dart
 var stream = session.messages.createStream('user_updates');
@@ -74,8 +78,6 @@ var subscription = stream.listen((message) {
 subscription.cancel();
 ```
 
-In the above example, the stream is first created and then canceled.
-
 ### Adding a listener
 
 To add a listener to a channel, use the `addListener` method. The listener will be called whenever a message is posted to the channel.
@@ -86,7 +88,7 @@ session.messages.addListener('user_updates', (message) {
 });
 ```
 
-In the above example, the listener will be called whenever a message is posted to the `user_updates` channel. The listener will be called regardless if a message is published globally by another server or internally by the same server.
+In the above example, the listener will be called whenever a message is posted to the `user_updates` channel. The listener will be called regardless of whether a message is published globally by another server or internally by the same server.
 
 #### Listener lifecycle
 

docs/06-concepts/17-backward-compatibility.md

@@ -1,3 +1,7 @@
+---
+description: Keep your Serverpod server compatible with older client versions by following rules around endpoint signatures, serialized model fields, and future call methods.
+---
+
 # Backward compatibility
 
 As your app evolves, features will be added or changed. However, your users may still use older versions of the app as not everyone will update to the latest version and automatic updates through the app stores take time. Therefore it may be essential to make updates to your server compatible with older app versions.
@@ -41,7 +45,7 @@ class TeamV2Endpoint extends TeamEndpoint {
 }
 ```
 
-In the above example, we created a new `TeamV2` endpoint, which hides the `join` method and instead exposes a `joinWithCode` method with the added parameter and the new return type. Additionally all the other inherited (and untouched) methods from the parent class are exposed.
+In the above example, we created a new `TeamV2` endpoint, which hides the `join` method and instead exposes a `joinWithCode` method with the added parameter and the new return type. Additionally, all the other inherited (and untouched) methods from the parent class are exposed.
 
 While we may have liked to re-use the `join` method name, Dart inheritance rules do not allow doing so. Otherwise, we would have to write the endpoint from scratch, meaning without inheritance, and re-implement all methods we would like to keep.