From 40c01e055255e256bae147f9d5fdf1a795b3a47c Mon Sep 17 00:00:00 2001 From: Shannon Anahata Date: Wed, 4 Feb 2026 14:58:04 -0800 Subject: [PATCH 1/3] updated contributing docs with style guide. Added vale as an optional IDE prose linting tool --- .github/styles/Sentry/Headings.yml | 31 ++ .github/styles/Sentry/InclusiveLanguage.yml | 13 + .github/styles/Sentry/MarketingSpeak.yml | 36 ++ .github/styles/Sentry/ProductNames.yml | 15 + .github/styles/Sentry/SentenceLength.yml | 8 + .github/styles/Sentry/Wordiness.yml | 21 ++ .../config/vocabularies/Sentry/accept.txt | 107 ++++++ .../config/vocabularies/Sentry/reject.txt | 5 + .gitignore | 5 +- .vale.ini | 33 ++ AGENTS.md | 29 ++ docs/contributing/approach/index.mdx | 4 +- docs/contributing/approach/style-guide.mdx | 348 ++++++++++++++++++ docs/contributing/environment.mdx | 40 ++ 14 files changed, 693 insertions(+), 2 deletions(-) create mode 100644 .github/styles/Sentry/Headings.yml create mode 100644 .github/styles/Sentry/InclusiveLanguage.yml create mode 100644 .github/styles/Sentry/MarketingSpeak.yml create mode 100644 .github/styles/Sentry/ProductNames.yml create mode 100644 .github/styles/Sentry/SentenceLength.yml create mode 100644 .github/styles/Sentry/Wordiness.yml create mode 100644 .github/styles/config/vocabularies/Sentry/accept.txt create mode 100644 .github/styles/config/vocabularies/Sentry/reject.txt create mode 100644 .vale.ini create mode 100644 docs/contributing/approach/style-guide.mdx diff --git a/.github/styles/Sentry/Headings.yml b/.github/styles/Sentry/Headings.yml new file mode 100644 index 0000000000000..642e5ecd6775a --- /dev/null +++ b/.github/styles/Sentry/Headings.yml @@ -0,0 +1,31 @@ +# Enforce Title Case for headings +extends: capitalization +message: "Use Title Case for headings: '%s'" +level: suggestion +scope: heading +match: $title +style: AP +# Allow certain words to be lowercase in titles +indicators: + - ":" +exceptions: + - a + - an + - and + - as + - at + - but + - by + - for + - in + - nor + - of + - on + - or + - so + - the + - to + - up + - yet + - vs + - via diff --git a/.github/styles/Sentry/InclusiveLanguage.yml b/.github/styles/Sentry/InclusiveLanguage.yml new file mode 100644 index 0000000000000..3c5024aa426c6 --- /dev/null +++ b/.github/styles/Sentry/InclusiveLanguage.yml @@ -0,0 +1,13 @@ +# Sentry inclusive language rules +# See: https://develop.sentry.dev/getting-started/inclusive-language/ +extends: substitution +message: "Use '%s' instead of '%s' for inclusive language." +level: warning +ignorecase: true +swap: + blacklist: blocklist + whitelist: allowlist + blacklisted: blocked + whitelisted: allowed + master/slave: primary/replica + grandfathered: legacy diff --git a/.github/styles/Sentry/MarketingSpeak.yml b/.github/styles/Sentry/MarketingSpeak.yml new file mode 100644 index 0000000000000..bdda4b039f781 --- /dev/null +++ b/.github/styles/Sentry/MarketingSpeak.yml @@ -0,0 +1,36 @@ +# Avoid corporate marketing language +extends: existence +message: "Avoid marketing speak: '%s'. Be direct and specific instead." +level: suggestion +ignorecase: true +tokens: + - best-in-class + - best in class + - world-class + - world class + - cutting-edge + - cutting edge + - industry-leading + - industry leading + - leverage + - leveraging + - leverages + - synergy + - synergies + - synergize + - paradigm + - paradigm shift + - game-changer + - game changer + - revolutionary + - revolutionize + - disruptive + - next-generation + - next generation + - bleeding-edge + - bleeding edge + - robust solution + - seamlessly + - empower + - empowers + - empowering diff --git a/.github/styles/Sentry/ProductNames.yml b/.github/styles/Sentry/ProductNames.yml new file mode 100644 index 0000000000000..81d13062c1146 --- /dev/null +++ b/.github/styles/Sentry/ProductNames.yml @@ -0,0 +1,15 @@ +# Ensure proper capitalization of Sentry product names +extends: substitution +message: "Use '%s' instead of '%s' for proper capitalization." +level: warning +ignorecase: false +swap: + '(? Projects**. + +### Word Choice +- Use "blocklist/allowlist" not "blacklist/whitelist" +- Use "primary/replica" not "master/slave" +- Use "to" not "in order to" +- Use "use" not "utilize" +- Verb forms: "set up" (verb) vs "setup" (noun), "log in" vs "login" + +For the complete style guide, see: https://docs.sentry.io/contributing/approach/style-guide/ + ## Developer Documentation (develop-docs/) When writing requirements in `develop-docs/`: diff --git a/docs/contributing/approach/index.mdx b/docs/contributing/approach/index.mdx index 5f09074fe2b33..b84cb2709412e 100644 --- a/docs/contributing/approach/index.mdx +++ b/docs/contributing/approach/index.mdx @@ -34,6 +34,8 @@ Keep these concepts in mind when contributing to docs: 1. Technical accuracy is our primary consideration. Our content helps every developer diagnose, fix, and optimize their code. 2. Use inclusive language, which we discuss more fully [here](https://develop.sentry.dev/getting-started/inclusive-language/). -3. Feedback is a gift - share your PR so we can improve our content. +3. Follow our [Style Guide](/contributing/approach/style-guide/) for tone, voice, and formatting standards. +4. For larger documentation updates, use the docs-review agent skill in Cursor or refer to the `AGENTS.md` file for AI assistant guidance on maintaining Sentry's voice and style. +5. Feedback is a gift - share your PR so we can improve our content. diff --git a/docs/contributing/approach/style-guide.mdx b/docs/contributing/approach/style-guide.mdx new file mode 100644 index 0000000000000..08a3505b28231 --- /dev/null +++ b/docs/contributing/approach/style-guide.mdx @@ -0,0 +1,348 @@ +--- +title: Style Guide +noindex: true +sidebar_order: 99 +--- + +This style guide helps contributors write documentation that matches the Sentry voice. Our goal is to help developers diagnose, fix, and optimize their code without getting in their way. We write documentation that is easy to understand, honest, concise and a little bit playful. + +## Tone & Voice + +### Supportive Peer + +Write like a developer talking to another developer. Directly address the reader to put them in the driver's seat. + + ++++ + + + + + + + + + + + + + +
DoDon't
"You're going to step through this code snippet.""The user will step through the code snippet."
"Configure the SDK.""One must configure the SDK."
+ +### Direct & Honest + +Avoid marketing terms like "best-in-class," "leverage," or "synergy." Be honest about functionality, focus on the value add, and how implement. + + ++++ + + + + + + + + + + + + + +
DoDon't
"Logs are a great way to add context to errors. Retry loops, fallback logic, and silent failures often show up in logs long before an error fires.""Logs help you spend less time searching and more time fixing. "
"Sentry captures errors automatically.""Sentry provides best-in-class error capturing capabilities."
+ +### Confident but Humble + +You are an expert, but you don't take yourself too seriously. + +### Inclusive + +Use language that helps anyone who finds our documentation feel welcome. See our [inclusive language guidelines](https://develop.sentry.dev/getting-started/inclusive-language/) for terms to avoid. + +## Stylistic Rules + +### American English + +Use U.S. spelling and grammar conventions. + + ++++ + + + + + + + + + + + + + + + + + +
DoDon't
colorcolour
organizeorganise
centercentre
+ +### Scannability + +Prioritize short paragraphs (2-3 sentences max). Use bullet points for lists. Developers are busy and scan documentation rather than reading every word. + + ++++ + + + + + + + + + +
DoDon't
+ +The SDK automatically captures unhandled exceptions. You can also capture errors manually using `captureException()`. + + + +The SDK automatically captures unhandled exceptions that occur in your application. In addition to this automatic error capturing functionality, you also have the ability to manually capture errors and exceptions using the `captureException()` method, which gives you more control over what gets reported to Sentry and when it gets reported. + +
+ +### Active Voice + +Use active voice. It's clearer and more direct. + + ++++ + + + + + + + + + + + + + + + + + +
DoDon't
"Sentry groups similar errors.""Similar errors are grouped by Sentry."
"The SDK sends events to Sentry.""Events are sent to Sentry by the SDK."
"Configure the sample rate.""The sample rate should be configured."
+ +### Headings + +Use Title Case for all headings (H1-H6). Never follow a headline with another headline; there must always be body text between them. + + ++++ + + + + + + + + + + + + + + + + + +
DoDon't
Getting StartedGetting started
Set Up Your ProjectSet up your project
Configure the SDKConfigure The Sdk
+ +## Formatting Standards + +### Code First + +Documentation is for developers. Provide clear, runnable code examples using modern syntax. Show the code, then explain it. + +### Bold for Emphasis + +Use **bold** to guide the eye to key actions or critical warnings. Use sparingly. + +### UI References + +When referencing UI elements: +- Use **bold** for button names and menu items: Click **Save Changes** +- Use the exact text that appears in the UI +- Use ">" to show menu paths: **Settings > Projects > Client Keys** + +### Technical Terms + +Capitalize well-known technical terms consistently: +- Single Sign-On (not single sign-on) +- Time-series (not time series or timeseries) +- JavaScript (not Javascript or javascript) + +## Word List & Terminology + +### Preferred Terms + + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Instead ofUseReason
blacklistblocklistInclusive language
whitelistallowlistInclusive language
master/slaveprimary/replicaInclusive language
grandfatheredlegacyInclusive language
click onclickSimpler
in order totoSimpler
utilizeuseSimpler
prior tobeforeSimpler
+ +### Verb vs. Noun Forms + + ++++ + + + + + + + + + + + + + + + + + +
Verb (action)Noun (thing)
set upsetup
log inlogin
sign upsignup
+ +Examples: +- "Set up your project" (verb) +- "Complete the setup" (noun) +- "Log in to Sentry" (verb) +- "Go to the login page" (noun) + +### Product Names + +Always capitalize Sentry product names: +- Sentry (not sentry) +- Sentry SDK (not Sentry sdk) +- DSN (not dsn) + +## The Sentry Spirit + +### Pixels Matter + +Pay attention to the details. Ensure technical accuracy above all else. If you're uncertain about something, verify it or ask. + +## Examples + +### Good: Direct and Scannable + +> Install the SDK using your package manager: +> +> ```bash +> npm install @sentry/node +> ``` +> +> Initialize Sentry in your application's entry point. The `DSN` is required; consider adding tracing, logs, and metrics for even more context and faster debugging. + +### Bad: Wordy and Passive + +> In this section, we will be walking you through the process of installing the SDK. The installation can be performed using your preferred package manager. Once the installation has been completed by you, the SDK will need to be initialized in your application's entry point file. + +### Good: Honest About Limitations + +> This integration doesn't support streaming responses yet. You can manually instrument streaming calls. + +### Bad: Vague and Marketing-speak + +> This integration provides comprehensive support for most use cases, enabling developers to leverage the full power of the platform. + +## Review Checklist + +When writing or reviewing documentation, verify: + +- [ ] **Tone:** Does it sound like a developer talking to a peer? +- [ ] **Directness:** Is the content free of fluff? +- [ ] **Scannability:** Are paragraphs short (2-3 sentences)? Are lists used appropriately? +- [ ] **Headings:** Title Case? No stacked headlines without text between them? +- [ ] **Active Voice:** Is passive voice avoided where possible? +- [ ] **Code Examples:** Are they clear, runnable, and using modern syntax? +- [ ] **American English:** Are spellings consistent with U.S. conventions? +- [ ] **Inclusive Language:** Are outdated or exclusionary terms avoided? + +## Style Linting + +We use [Vale](https://vale.sh/) as an advisory prose linter. It checks for style issues like passive voice, overly long sentences, and inclusive language violations. + +Vale is optional but recommended. See [Development Environment](/contributing/environment/#prose-linting-with-vale) for setup instructions. diff --git a/docs/contributing/environment.mdx b/docs/contributing/environment.mdx index c1336a595c46c..028d3e1876b8d 100644 --- a/docs/contributing/environment.mdx +++ b/docs/contributing/environment.mdx @@ -81,3 +81,43 @@ Then run: ```bash yarn lint:typos ``` + +### Style Guide Linting With Vale + +We use [Vale](https://vale.sh/) as an advisory prose linter to check for style issues like passive voice, overly long sentences, and inclusive language. Vale is optional but recommended for contributors writing documentation. + +**Installing Vale:** + +- macOS: `brew install vale` +- Windows: `choco install vale` or `scoop install vale` +- Linux: Download from [GitHub releases](https://github.com/errata-ai/vale/releases) +- Cross-platform: `go install github.com/errata-ai/vale/v3/cmd/vale@latest` + +**First-time setup:** + +After installing Vale, sync the required style packages: + +```bash +vale sync +``` + +**Running Vale:** + +```bash +# Check all docs +vale docs/ + +# Check a specific file +vale docs/platforms/javascript/index.mdx + +# Check develop-docs +vale develop-docs/ +``` + +Vale will show suggestions for improving your prose. These are advisory only and not enforced in CI. + +**VS Code integration:** + +Install the [Vale VS Code extension](https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode) for inline suggestions as you write. + +For more details on our writing standards, see the [Style Guide](/contributing/approach/style-guide/). From 3da955a31adc54dd491e49f103a473999a06e5e1 Mon Sep 17 00:00:00 2001 From: Shannon Anahata Date: Wed, 4 Feb 2026 15:10:37 -0800 Subject: [PATCH 2/3] fixing dupe info --- .gitignore | 3 --- 1 file changed, 3 deletions(-) diff --git a/.gitignore b/.gitignore index 306e5f6ad6174..2092bdec0943f 100644 --- a/.gitignore +++ b/.gitignore @@ -109,8 +109,5 @@ yalc.lock /public/doctree.json /public/doctree-dev.json -# Claude Code local files -.claude/settings.local.json - # Vale synced packages (downloaded via `vale sync`) .github/styles/write-good/ \ No newline at end of file From 619b6357aa42e30a89643f3f6adf892875164fbd Mon Sep 17 00:00:00 2001 From: Shannon Anahata Date: Thu, 5 Feb 2026 10:01:28 -0800 Subject: [PATCH 3/3] Update terminology from 'master/slave' to 'primary/secondary' --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 7e421274909c7..fd12f8900027d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -73,7 +73,7 @@ When writing or editing documentation content in `docs/`: ### Word Choice - Use "blocklist/allowlist" not "blacklist/whitelist" -- Use "primary/replica" not "master/slave" +- Use "master/secondary", "primary/secondary" not "master/slave" - Use "to" not "in order to" - Use "use" not "utilize" - Verb forms: "set up" (verb) vs "setup" (noun), "log in" vs "login"