Updated instances of passive voice via Copilot #11064
Open
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
Contributor
There was a problem hiding this comment.
Pull Request Overview
This PR updates multiple documentation files to improve clarity, conciseness, and alignment with Braze's documentation style guidelines. The changes primarily focus on removing time-anchored language, simplifying phrasing, and using more direct active voice constructions.
Key changes include:
- Removing time-anchored words and phrases ("will", "currently", etc.)
- Simplifying sentence structures for better readability
- Using more active and direct language
- Improving consistency in terminology and phrasing
Reviewed Changes
Copilot reviewed 24 out of 24 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| managing_user_subscriptions.md | Simplified language throughout, removed time-anchored phrasing, improved clarity in subscription state descriptions |
| inbox_vision.md | Condensed explanations, removed unnecessary qualifiers, improved directness |
| creating_an_email_campaign.md | Streamlined instructions, removed future tense usage, made language more concise |
| ssl.md | Simplified technical explanations, removed passive voice, improved clarity |
| email_validation.md | Made validation process descriptions more direct and concise |
| authentication.md | Simplified DMARC policy explanations, removed redundant language |
| duplicate_emails.md | Clarified deduplication behavior with more direct language |
| card_creation.md | Improved clarity around card creation timing and behavior |
| create.md | Simplified Canvas vs campaign guidance, clarified card behavior |
| uninstall_tracking.md | Made tracking process descriptions more direct |
| Multiple partner integration files | Standardized language around integration confirmation status |
| dixa.md | Minor clarification improvement |
| {% alert important %} | ||
| The email drag-and-drop editor currently does not support setting a document `<title>` element. As a result, the accessibility scanner will always fail this check.<br><br> | ||
| We're tracking this limitation for future improvements. If this affects your workflows or your users, [share your feedback]({{site.baseurl}}/user_guide/administrative/access_braze/navigation/#sharing-feedback) so we can prioritize the most impactful fixes. | ||
| The drag-and-drop editor does not support setting a document `<title>` element, so the accessibility scanner always fails this check.<br><br>We are tracking this limitation for improvements. If this affects your workflows or your users, [share your feedback]({{site.baseurl}}/user_guide/administrative/access_braze/navigation/#sharing-feedback) so we can prioritize impactful fixes. |
There was a problem hiding this comment.
The phrase 'We are tracking' uses present continuous tense which could be considered time-anchored. Per the coding guidelines, avoid phrases that anchor writing to a point in time. Consider rephrasing to 'Braze is tracking this limitation' or 'This limitation is tracked for future improvements.'
Suggested change
| The drag-and-drop editor does not support setting a document `<title>` element, so the accessibility scanner always fails this check.<br><br>We are tracking this limitation for improvements. If this affects your workflows or your users, [share your feedback]({{site.baseurl}}/user_guide/administrative/access_braze/navigation/#sharing-feedback) so we can prioritize impactful fixes. | |
| The drag-and-drop editor does not support setting a document `<title>` element, so the accessibility scanner always fails this check.<br><br>This limitation is tracked for future improvements. If this affects your workflows or your users, [share your feedback]({{site.baseurl}}/user_guide/administrative/access_braze/navigation/#sharing-feedback) so we can prioritize impactful fixes. |
| <td class="tg-0pky">Cards are created for every eligible user in the segment at the time of launch. For large audiences, we recommend to select <b>At First Impression</b>, as cards will be available more quickly after launch.</td> | ||
| <td class="tg-0pky">Cards are created the first time a user tries to view the card, so it may take 1-2 seconds to display on the first impression.</td> | ||
| <td class="tg-0pky">Braze creates cards for every eligible user in the segment at launch time. For large audiences, select <b>At First Impression</b> so cards are available more quickly after launch.</td> | ||
| <td class="tg-0pky">Braze creates a card the first time a user tries to view it, so it may take 1–2 seconds to display on the first impression.</td> |
There was a problem hiding this comment.
[nitpick] The en dash '–' should be consistent with the hyphen used elsewhere in the documentation for ranges. Use either '1-2' or '1–2' consistently throughout.
Contributor
There was a problem hiding this comment.
@atom-evens Could be worth trying that out in a later PR!
| ## Email subscription updates | ||
|
|
||
| Braze automatically checks for and removes duplicate email addresses when an email campaign is sent. This way an email is only sent once and is "deduped," which checks that it doesn't hit the same email multiple times even if multiple user profiles share a common address. | ||
| Braze automatically checks for and removes duplicate email addresses when it sends an email campaign. This ensures Braze sends the email only once even if multiple user profiles share an address. |
Contributor
There was a problem hiding this comment.
Suggested change
| Braze automatically checks for and removes duplicate email addresses when it sends an email campaign. This ensures Braze sends the email only once even if multiple user profiles share an address. | |
| Braze automatically checks for and removes duplicate email addresses when it sends an email campaign. This prevents Braze from sending the email more than once even if multiple user profiles share an address. |
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.
Why are you making this change? (required)
These changes are the result of Copilot fixing instances of passive voice throughout the documentation. I did my best to check each edit (so as to hopefully avoid any extra work on the reviewer's part), but please spot check these files to ensure now errors are introduced.
Related PRs, issues, or features (optional)
Feature release date (optional)
Contributor checklist
Submitting for review
If your PR meets the above requirements, select Ready for review, then add a reviewer:
@braze-inc/docs-teamin a comment below.braze-inc/docs-teaminstead.Thanks for contributing! We look forward to reading your work.