From 77f9d69cb7af09cba76f0c85b94ce13f81a6c1e5 Mon Sep 17 00:00:00 2001 From: jalmeida9457 Date: Thu, 30 Oct 2025 15:36:31 -0400 Subject: [PATCH] Improve documentation clarity by removing filler words and passive voice MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit addresses issue #354 by removing unnecessary filler words and converting passive voice to active voice across the Broadway documentation. Key changes across README.md and guide files: - Remove "just" from "you just need to" → "add it as" - Remove "simply" from "simply delegates to" → "delegates to" - Remove "already" from "come already with" → "come with" - Remove "can easily" from "you can easily install" → "install" - Fix comma placement in "First we update" → "First, we update" - Fix "then we print" → "then print" for parallel structure - Fix "However those" → "However, those" (missing comma) - Remove duplicate word "using using" → "using" - Convert "you need to add" → "add it" (more direct) - Convert "You can add" → "Add" (imperative form) These changes make the documentation more direct and concise while maintaining clarity and professionalism, following the guidance from issue #354 and PR #355 feedback. Fixes #354 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- README.md | 2 +- guides/examples/amazon-sqs.md | 16 ++++++++-------- guides/examples/apache-kafka.md | 12 ++++++------ guides/examples/google-cloud-pubsub.md | 14 +++++++------- guides/examples/rabbitmq.md | 10 +++++----- 5 files changed, 27 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index b404b592..c5278495 100644 --- a/README.md +++ b/README.md @@ -82,7 +82,7 @@ defmodule MyBroadway do end ``` -Once your Broadway module is defined, you just need to add it as a child of your application supervision tree as `{MyBroadway, []}`. +Once your Broadway module is defined, add it as a child of your application supervision tree as `{MyBroadway, []}`. ## Comparison to Flow diff --git a/guides/examples/amazon-sqs.md b/guides/examples/amazon-sqs.md index 67479f6d..1c989b6b 100644 --- a/guides/examples/amazon-sqs.md +++ b/guides/examples/amazon-sqs.md @@ -33,7 +33,7 @@ In order to use Broadway with SQS, we need to: Amazon provides a comprehensive [Step-by-step Guide](https://aws.amazon.com/getting-started/tutorials/send-messages-distributed-applications/) on creating SQS queues. In case you don't have an AWS account and want to -test Broadway locally, use can easily install [ElasticMQ](https://github.com/softwaremill/elasticmq), +test Broadway locally, install [ElasticMQ](https://github.com/softwaremill/elasticmq), which is a message queue system that offers a SQS-compatible query interface. ## Configure the project @@ -71,7 +71,7 @@ pipeline, we need to define three functions: `start_link/1`, `handle_message/3` and `handle_batch/4`. We will cover `start_link/1` in this section and the `handle_` callbacks in the next one. -Similar to other process-based behaviour, `start_link/1` simply +Similar to other process-based behaviour, `start_link/1` delegates to `Broadway.start_link/2`, which should define the producers, processors, and batchers in the Broadway pipeline. Assuming we want to consume messages from a queue called @@ -161,17 +161,17 @@ all messages received from the queue are just numbers: end We are not doing anything fancy here, but it should be enough for our -purpose. First we update the message's data individually inside -`handle_message/3` and then we print each batch inside `handle_batch/4`. +purpose. First, we update the message's data individually inside +`handle_message/3` and then print each batch inside `handle_batch/4`. For more information, see `c:Broadway.handle_message/3` and `c:Broadway.handle_batch/4`. ## Run the Broadway pipeline -To run your `Broadway` pipeline, you just need to add as a child in +To run your `Broadway` pipeline, add it as a child in a supervision tree. Most applications have a supervision tree defined -at `lib/my_app/application.ex`. You can add Broadway as a child to a +at `lib/my_app/application.ex`. Add Broadway as a child to a supervisor as follows: children = [ @@ -187,8 +187,8 @@ in the supervision tree. ## Tuning the configuration -Some of the configuration options available for Broadway come already with a -"reasonable" default value. However those values might not suit your +Some of the configuration options available for Broadway come with a +"reasonable" default value. However, those values might not suit your requirements. Depending on the number of messages you get, how much processing they need and how much IO work is going to take place, you might need completely different values to optimize the flow of your pipeline. The `concurrency` option diff --git a/guides/examples/apache-kafka.md b/guides/examples/apache-kafka.md index 97f9477b..2a449776 100644 --- a/guides/examples/apache-kafka.md +++ b/guides/examples/apache-kafka.md @@ -69,7 +69,7 @@ we need to define three functions: `start_link/1`, `handle_message/3` and optionally `handle_batch/4`. We will cover `start_link/1` in this section and the `handle_` callbacks in the next one. -Similar to other process-based behaviours, `start_link/1` simply +Similar to other process-based behaviours, `start_link/1` delegates to `Broadway.start_link/2`, which should define the producers, processors, and batchers in the Broadway pipeline. Assuming we want to consume messages from a topic called @@ -152,7 +152,7 @@ all messages received from the topic are just numbers: We are not doing anything fancy here, but it should be enough for our purpose. First, we update the message's data individually inside -`handle_message/3` and then we print each batch inside `handle_batch/4`. +`handle_message/3` and then print each batch inside `handle_batch/4`. For more information, see `c:Broadway.handle_message/3` and `c:Broadway.handle_batch/4`. @@ -163,9 +163,9 @@ For more information, see `c:Broadway.handle_message/3` and ## Run the Broadway pipeline -To run your `Broadway` pipeline, you just need to add as a child in +To run your `Broadway` pipeline, add it as a child in a supervision tree. Most applications have a supervision tree defined -at `lib/my_app/application.ex`. You can add Broadway as a child to a +at `lib/my_app/application.ex`. Add Broadway as a child to a supervisor as follows: children = [ @@ -193,7 +193,7 @@ under the hood to communicate with Kafka. ### Sending messages to Kafka -Finally, we can send some sample messages to Kafka using using `:brod` with the following snippet: +Finally, we can send some sample messages to Kafka using `:brod` with the following snippet: topic = "test" client_id = :my_client @@ -228,7 +228,7 @@ You should see the output showing the generated batches: ## Tuning the configuration -Some of the configuration options available for Broadway come already with a +Some of the configuration options available for Broadway come with a "reasonable" default value. However, those values might not suit your requirements. Depending on the number of records you get, how much processing they need and how much IO work is going to take place, you might need completely diff --git a/guides/examples/google-cloud-pubsub.md b/guides/examples/google-cloud-pubsub.md index 2dbbc594..97f32500 100644 --- a/guides/examples/google-cloud-pubsub.md +++ b/guides/examples/google-cloud-pubsub.md @@ -118,7 +118,7 @@ Broadway is a process-based behaviour and to define a Broadway pipeline, we need functions: `start_link/1`, `handle_message/3` and `handle_batch/4`. We will cover `start_link/1` in this section and the `handle_` callbacks in the next one. -Similar to other process-based behaviour, `start_link/1` simply delegates to +Similar to other process-based behaviour, `start_link/1` delegates to `Broadway.start_link/2`, which should define the producers, processors, and batchers in the Broadway pipeline. Assuming we want to consume messages from the `test-subscription`, the minimal configuration would be: @@ -187,16 +187,16 @@ processor calls `String.upcase/1` on them: end end -We are not doing anything fancy here, but it should be enough for our purpose. First we update the -message's data individually inside `handle_message/3` and then we print each batch inside +We are not doing anything fancy here, but it should be enough for our purpose. First, we update the +message's data individually inside `handle_message/3` and then print each batch inside `handle_batch/4`. For more information, see `c:Broadway.handle_message/3` and `c:Broadway.handle_batch/4`. ## Run the Broadway pipeline -To run your `Broadway` pipeline, you need to add it as a child in a supervision tree. Most -applications have a supervision tree defined at `lib/my_app/application.ex`. You can add Broadway +To run your `Broadway` pipeline, add it as a child in a supervision tree. Most +applications have a supervision tree defined at `lib/my_app/application.ex`. Add Broadway as a child to a supervisor as follows: children = [ @@ -239,8 +239,8 @@ Got batch of finished jobs from processors, sending ACKs to Pub/Sub as a batch.: ## Tuning the configuration -Some of the configuration options available for Broadway come already with a -"reasonable" default value. However those values might not suit your +Some of the configuration options available for Broadway come with a +"reasonable" default value. However, those values might not suit your requirements. Depending on the number of messages you get, how much processing they need and how much IO work is going to take place, you might need completely different values to optimize the flow of your pipeline. The `concurrency` option diff --git a/guides/examples/rabbitmq.md b/guides/examples/rabbitmq.md index f9ee8656..937ff874 100644 --- a/guides/examples/rabbitmq.md +++ b/guides/examples/rabbitmq.md @@ -76,7 +76,7 @@ we need to define three functions: `start_link/1`, `handle_message/3` and optionally `handle_batch/4`. We will cover `start_link/1` in this section and the `handle_` callbacks in the next one. -Similar to other process-based behaviours, `start_link/1` simply +Similar to other process-based behaviours, `start_link/1` delegates to `Broadway.start_link/2`, which should define the producers, processors, and batchers in the Broadway pipeline. Assuming we want to consume messages from a queue called @@ -168,7 +168,7 @@ all messages received from the queue are just numbers: We are not doing anything fancy here, but it should be enough for our purpose. First, we update the message's data individually inside -`handle_message/3` and then we print each batch inside `handle_batch/4`. +`handle_message/3` and then print each batch inside `handle_batch/4`. For more information, see `c:Broadway.handle_message/3` and `c:Broadway.handle_batch/4`. @@ -181,9 +181,9 @@ For more information, see `c:Broadway.handle_message/3` and ## Run the Broadway pipeline -To run your `Broadway` pipeline, you just need to add as a child in +To run your `Broadway` pipeline, add it as a child in a supervision tree. Most applications have a supervision tree defined -at `lib/my_app/application.ex`. You can add Broadway as a child to a +at `lib/my_app/application.ex`. Add Broadway as a child to a supervisor as follows: children = [ @@ -241,7 +241,7 @@ You should see the output showing the generated batches: ## Tuning the configuration -Some of the configuration options available for Broadway come already with a +Some of the configuration options available for Broadway come with a "reasonable" default value. However, those values might not suit your requirements. Depending on the number of messages you get, how much processing they need and how much IO work is going to take place, you might need completely