docs: rewrite first-person voice to comply with second-person style guide#585
Open
tomarra wants to merge 13 commits into
Open
docs: rewrite first-person voice to comply with second-person style guide#585tomarra wants to merge 13 commits into
tomarra wants to merge 13 commits into
Conversation
…ages
Per the marketing content guidelines, docs should be written in second
person. Rewrites the three largest offenders (230 of 487 total
first-person pronoun instances):
- system/security.mdx (139 instances): a security/policy page, almost
entirely first-person statements about what Shorebird as a company
does ("we use Google Cloud", "we do not sell your data"). These
can't become "you" statements without changing the facts, so they're
rephrased to third person ("Shorebird uses...") or passive voice
instead.
- code-push/system-architecture.mdx (48 instances): similar pattern -
describes Shorebird's own internal architecture and fork history
("we forked Flutter", "our database"), rephrased the same way.
- code-push/faq.mdx (43 instances): a mix of company statements
(rephrased to third person/passive) and instructional recommendations
("we recommend X" -> "X is recommended" or dropped the pronoun
entirely where the sentence reads fine without it).
Left headings untouched even where they contain "we" (e.g. "What
can't we use Shorebird Code Push for?") since Shorebird.SecondPerson
is scoped to paragraphs only, not headings - these were never flagged
and don't need to change.
This is a partial pass; the remaining ~40 files with first-person
instances will follow in subsequent commits.
…Flutter SDK guides
…ols, fastlane, symbols, release, rollback, update-strategies, architecture-trees, and flutter-version guides
… and getting-started pages
AbhishekDoshi26
approved these changes
Jul 3, 2026
Comment on lines
+87
to
+88
| to the price of your plan. You'll be notified via email once when you’re close | ||
| to your limit, and again when you’ve reached your limit. |
Member
There was a problem hiding this comment.
Maybe we should mention here that the account owner will be notified. As we have seen people reaching out that they haven't got emails as account owner is generic email
Contributor
Author
There was a problem hiding this comment.
Suggested change
| to the price of your plan. You'll be notified via email once when you’re close | |
| to your limit, and again when you’ve reached your limit. | |
| to the price of your plan. The account owner be notified via email once when you’re close | |
| to your limit, and again when you’ve reached your limit. |
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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.
Summary
Shorebird.SecondPersonstyle guideline.Shorebird.SecondPersononly scopes to paragraph text.A handful of
Shorebird.SecondPersonmatches remain and are intentional false positives from the pattern-matching rule, not first-person prose:security.mdx— URL slug#can-i-use-shorebird-in-my-countrysystem-architecture.mdx— "US" (United States), matched as the pronoun "us"faq.mdx— link text[How We Bill]quoting an actual page headinghybrid-apps/ios.mdx,hybrid-apps/android.mdx,release.mdx,security.mdx— "i.e." matched as the pronoun "i"account/orgs.mdx— the literal default org name "My Organization"Test plan
npm run buildsucceeds with no broken linksvale(with the not-yet-merged tooling from docs: add style checks for headings and content guidelines #576) shows 0 realShorebird.SecondPersonfindings acrosssrc/content/docs(only the documented false positives above remain)prettier --checkandcspellpass on every changed file