Documentation edits for concise, active voice #355
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…ice and add specificity
* added "messages" inside the bold after "the" was no longer breaking up an active phrase * Multiple "you" + verb instances in paragraph form required reworking to make active * I tried to get from active to passive with the minimum amount of edits and no change in the information being presented
* removed weak words would/should
* removed "should" * updated list layout
* removed "you want", "you can"s * Added context and formatting to the example * added example for `init/0` @doc
* removing some passive voice and weak words like "should" * minor rewrite for different word choice/sentence structure. *white space changes Note: If we don't like the formatting of the `c:prepare_for_start/2` parameters, here are the edits in paragraph form: The `module` parameter represents the Broadway module passed as the first argument to `Broadway.start_link/2`. The `options` parameter contains all the Broadway topology options passed as the second argument to `Broadway.start_link/2`.
* "in order to" * "simply" * "we need to"/"we can" * "you need to" * "blank of blanks" * "you should" * "never stops" (weakly double negative) * Change "you can blank" to "blank"
whatyouhide
reviewed
Apr 2, 2025
There was a problem hiding this comment.
This is a ton of changes, I think it might have been easier to review if split up into a few PRs (fix titlecase headers, remove most "you can"s, and another one maybe). I didn't read the whole PR but there are a few spots already where I think the changes might not really make sense, thoguhts?
| @@ -43,7 +43,7 @@ end | |||
|
|
|||
| ## A quick example: SQS integration | |||
|
|
|||
| Assuming you have added [`broadway_sqs`](https://github.com/dashbitco/broadway_sqs) as a dependency and configured your SQS credentials accordingly, you can consume Amazon SQS events in only 20 LOCs: | |||
| Assuming you have added [`broadway_sqs`](https://github.com/dashbitco/broadway_sqs) as a dependency and configured your SQS credentials accordingly, consume Amazon SQS events in only 20 LOCs: | |||
There was a problem hiding this comment.
I think this is significantly worse without you can?
| @@ -202,7 +201,7 @@ See the notes on [`Producer concurrency`](https://hexdocs.pm/broadway/Broadway.h | |||
| and [`Batcher concurrency`](https://hexdocs.pm/broadway/Broadway.html#module-batcher-concurrency) | |||
| for details. | |||
|
|
|||
| Here's an example on how you could tune them according to | |||
| Here's an example on how you tune them according to | |||
There was a problem hiding this comment.
Suggested change
| Here's an example on how you tune them according to | |
| Here's an example on how to tune them according to |
Think this reads better?
| @@ -236,5 +235,4 @@ your needs. | |||
| In order to get a good set of configurations for your pipeline, it's | |||
| important to respect the limitations of the servers you're running, | |||
| as well as the limitations of the services you're providing/consuming | |||
| data to/from. Broadway comes with telemetry, so you can measure your | |||
| pipeline and help ensure your changes are effective. | |||
| data to/from. Measure your pipeline with [telemetry](https://hexdocs.pm/telemetry/readme.html) to ensure your changes are effective. (It comes standard.) | |||
There was a problem hiding this comment.
I really don't think the parentheses there work well. What about
Suggested change
| data to/from. Measure your pipeline with [telemetry](https://hexdocs.pm/telemetry/readme.html) to ensure your changes are effective. (It comes standard.) | |
| data to/from. To measure your pipeline and ensure your changes are effective, use the [telemetry](https://hexdocs.pm/telemetry/readme.html) integration that comes with Broadway. |
| @@ -207,7 +201,7 @@ Finally, we can send some sample messages to Kafka using using `:brod` with the | |||
| :ok = :brod.produce_sync(client_id, topic, partition, _key="", "#{i}") | |||
| end) | |||
|
|
|||
| You should see the output showing the generated batches: | |||
| See the output showing the generated batches: | |||
There was a problem hiding this comment.
Nope I don't think this works well?
Pull Request Test Coverage Report for Build d7f4e00f6c0f6ddbd0b6e1a253eb787dd72157af-PR-355Details
💛 - Coveralls |
I can break it up no problem. 👍🤓 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Removing filler words and passive voice from docs #354