chore: incorporate review comments

to be squashed into the previous commit

Signed-off-by: Michael Adler <michael.adler@siemens.com>

CHANGELOG.md

@@ -19,8 +19,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- The response to a job status update always contains the workflow name now (see #11)
-
 ### Removed
 
 ## [0.1.0] - 2023-02-06

docs/operations.md

@@ -61,7 +61,7 @@ The status notifications are built using [server-sent events](https://developer.
  └────────┘                            └─────┘
 ```
 
-1. The client sends a `GET` request to the endpoint `/jobs/events` optionally supplying **filter parameters** to only
+1. The client sends a `GET` request to the endpoint `/jobs/events`, optionally providing [filter parameter](#filter-parameters) to only
    receive events for certain jobs.
 2. The server sets `Content-Type` to `text/event-stream`.
 3. The response body contains a stream of job events.
@@ -90,27 +90,45 @@ A single event has the following structure:
 
 - `CREATE`: a new job was created
 - `DELETE`: a job was deleted
-- `ADD_TAGS`: tags were added
-- `DELETE_TAGS`: tags were deleted
-- `UPDATE_STATUS`: a job's status was updated
-- `UPDATE_DEFINITION`: a job's definition was updated
+- `ADD_TAGS`: tags were added to the job
+- `DELETE_TAGS`: tags were deleted from the job
+- `UPDATE_STATUS`: job status was updated
+- `UPDATE_DEFINITION`: job definition was updated
 
-#### Example: Subscribe to multiple job ids
+#### Filter Parameters
 
-`wfxctl` provides a reference client implementation, e.g.
+Job events can be filtered using any combination of the following parameters:
+
+- Job IDs
+- Client IDs
+- Workflow Names
+
+This enables more precise control over the subscription to events.
+
+#### Examples
+
+The `wfxctl` tool offers a reference client implementation. The following command subscribes to **all** job events:
+
+```bash
+wfxctl job events
+```
+
+This may result in a large number of events, though. For a more targeted approach, filter parameters may be used, e.g.
 
 ```bash
 wfxctl job events --ids d305e539-1d41-4c95-b19a-2a7055c469d0,e692ad92-45e6-4164-b3fd-8c6aa884011c
 ```
 
+subscribes to events for jobs with IDs that match either of the two specified.
+
 #### Caveats
 
 1. Job status updates are dispatched asynchronously to prevent a subscriber from causing a delay in status updates.
-   Consequently, messages may be **delivered out-of-order**. This is typically not an issue; however, under
-   circumstances with high concurrency, such as multiple clients attempting to modify the same job or a single client
-   sending a burst of status updates, this behavior might occur.
-2. Server-Sent Events use unidirectional communication, which means that **message delivery is not guaranteed**. In
-   other words, there are scenarios where certain events may never reach the subscriber.
+   Consequently, messages may be delivered **out-of-order** as perceived by the client. This is typically not an issue;
+   however, under circumstances with high concurrency, such as multiple clients attempting to modify the same job or a
+   single client sending a burst of status updates, this behavior might occur.
+2. Server-Sent Events rely on one-way communication, and there is **no acknowledgment** or handshake protocol to ensure
+   message delivery. In other words, there are scenarios where certain events may never reach the subscriber.
 3. When scaling out horizontally, the load balancer should implement stickiness based on job IDs.
    Alternatively, the client can subscribe to updates from every wfx instance and subsequently aggregate the events it receives.
 4. Browsers typically limit SSE connections (6 per domain). HTTP/2 can be used instead (100 connections by default) or some kind of