chore: Add engineering inclusive language guidance

[marandaneto]

Problem

Engineering guidance for inclusive technical language was only covered briefly in the docs style guide. We needed a more engineering-focused handbook page that covers code, APIs, config names, migrations, and PR review.

Preview builds also fetched Strapi-backed SDK reference data even though minimal PR previews don't create SDK reference pages, which made previews vulnerable to unrelated transient Strapi failures.

Changes

• Added a new Engineering → Coding conventions page for inclusive language in engineering.
• Reworked the page flow to separate guidance for choosing new language from guidance for changing existing code.
• Documented preferred terms, examples, and guidance for changing existing code safely.
• Clarified that the preferred-language table is not exhaustive and engineers should use common sense.
• Added more examples for words like cripple, normal, and suffers from.
• Added guidance to align with Developer Experience and feature owners for broad, cross-cutting changes.
• Added guidance to enable inclusive language linting when available, with SwiftLint as an example.
• Added the new page to the Engineering sidebar.
• Updated the docs style guide to link to the new engineering guidance.
• Skipped SDK reference fetching during minimal builds, since SDK reference pages are not created in that mode.

Checklist

• I've read the docs and/or content style guides.
• Words are spelled using American English
• Use relative URLs for internal links
• I've checked the pages added or changed in the Vercel preview build
• If I moved a page, I added a redirect in vercel.json

preview https://c755219a.posthog-preview.pages.dev/handbook/engineering/conventions/inclusive-language

[github-actions]

Deploy preview

Status	Details	Updated (UTC)
🟢 Ready	View preview	May 29, 2026 11:47AM

[github-actions]

Vale prose linter → found 16 errors, 28 warnings, 0 suggestions in your markdown

Full report → Copy the linter results into an LLM to batch-fix issues.

Linter being weird? Update the rules!

contents/handbook/docs-and-wizard/docs-style-guide.mdx — 16 errors, 27 warnings, 0 suggestions

Line	Severity	Message	Rule
14:98	warning	Use American English. Use 'judgment' instead of 'judgement'.	PostHogBase.AmericanEnglish
80:50	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	PostHogBase.EnDash
80:97	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	PostHogBase.EnDash
98:88	warning	Capitalize 'Product Analytics' for PostHog's product. Use 'product analytics' for the general industry concept.	PostHogBase.ProductNames
102:19	warning	Capitalize 'Session Replay' for PostHog's product. Use 'session replay' for the general industry concept.	PostHogBase.ProductNames
104:155	warning	Capitalize 'Product Analytics' for PostHog's product. Use 'product analytics' for the general industry concept.	PostHogBase.ProductNames
112:5	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'Feature flags' for the general industry concept.	PostHogBase.ProductNames
112:82	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	PostHogBase.ProductNames
144:14	warning	Use American English. Use 'color' instead of 'colour'.	PostHogBase.AmericanEnglish
144:22	warning	Use American English. Use 'analyze' instead of 'analyse'.	PostHogBase.AmericanEnglish
144:41	warning	Use American English. Use 'license' instead of 'licence'.	PostHogBase.AmericanEnglish
160:38	warning	Capitalize 'Session Replay' for PostHog's product. Use 'session replay' for the general industry concept.	PostHogBase.ProductNames
160:58	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	PostHogBase.ProductNames
162:41	warning	Capitalize 'Session Replay' for PostHog's product. Use 'session replay' for the general industry concept.	PostHogBase.ProductNames
162:60	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	PostHogBase.ProductNames
176:36	warning	Use the Oxford comma before 'and' or 'or' in a list of three or more items.	PostHogBase.OxfordComma
180:174	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	PostHogBase.EnDash
186:76	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	PostHogBase.EnDash
194:31	warning	'initialisms' is a possible misspelling.	PostHogBase.Spelling
198:14	warning	Use 'SQL' instead of 'Sql'.	Vale.Terms
198:19	warning	Use 'API' instead of 'Api'.	Vale.Terms
198:24	warning	Use 'HTML' instead of 'Html'.	Vale.Terms
281:3	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'Feature flags' for the general industry concept.	PostHogBase.ProductNames
299:1	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	PostHogBase.EnDash
300:1	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	PostHogBase.EnDash
301:1	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	PostHogBase.EnDash
301:58	warning	Capitalize 'Experiments' for PostHog's product. Use 'experiments' for the general industry concept.	PostHogBase.ProductNames
307:57	warning	Capitalize 'Experiments' for PostHog's product. Use 'experiments' for the general industry concept.	PostHogBase.ProductNames
327:7	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	PostHogBase.ProductNames
337:29	warning	Capitalize 'Data Pipelines' for PostHog's product. Use 'data pipelines' for the general industry concept.	PostHogBase.ProductNames
365:1	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	PostHogBase.EnDash
366:1	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	PostHogBase.EnDash
367:1	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	PostHogBase.EnDash
369:26	warning	Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept.	PostHogBase.ProductNames
426:21	warning	Use descriptive link text instead of '[this link]'.	PostHogBase.DescriptiveLinkText
434:1	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	PostHogBase.EnDash
435:1	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	PostHogBase.EnDash
441:1	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	PostHogBase.EnDash
442:1	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	PostHogBase.EnDash
443:1	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	PostHogBase.EnDash
504:1	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	PostHogBase.EnDash
504:66	warning	'devtools' is a possible misspelling.	PostHogBase.Spelling
511:14	warning	Capitalize 'Workflows' for PostHog's product. Use 'workflows' for the general industry concept.	PostHogBase.ProductNames

contents/handbook/engineering/conventions/inclusive-language.md — 0 errors, 1 warnings, 0 suggestions

Line	Severity	Message	Rule
51:58	warning	'pathologizing' is a possible misspelling.	PostHogBase.Spelling

[ioannisj]

LG. I would also drop a note for enabling relevant linter rules when available. e.g https://realm.github.io/SwiftLint/inclusive_language.html

[marandaneto]

@ioannisj Added this in b25c31d — the Tooling section now recommends enabling inclusive language linting when the ecosystem supports it, with SwiftLint’s inclusive_language rule as an example.

[mattfield]

❤️

[marandaneto]

reason is CI:

error "gatsby-node.js" threw an error while running the sourceNodes lifecycle:

invalid json response body at https://better-animal-d658c56969.strapiapp.com/api/sdk-references?filters[referenceId][$eq]=posthog-go&filters[version][$containsi]=latest&pagination[page]=1&pagination[pageSize]=1&sort[0]=createdAt%3Adesc reason: Unexpected token '<', " <!DOCTYPE "... is not valid JSON

FetchError:invalid json response body at
https://better-animal-d658c56969.str/ apiapp.com/api/sdk-references?filters[referenceId][$eq]=posthog-go&filters[ver sion][$containsi]=latest&pagination[page]=1&pagination[pageSize]=1&sort[0]=cre atedAt%3Adesc reason: Unexpected token '<', " <!DOCTYPE "... is not valid JSON

• index.js:273
  [posthog.com]/[node-fetch@2.7.0]/[node-fetch]/lib/index.js:273:32

• task_queues:103 processTicksAndRejections
  node:internal/process/task_queues:103:5

• gatsby-node.js:1 e
  /home/runner/work/posthog.com/posthog.com/.cache/compiled/gatsby-node.js:1:2 05888

• async Promise.all

• gatsby-node.js:1
  /home/runner/work/posthog.com/posthog.com/.cache/compiled/gatsby-node.js:1:2 06034

• async Promise.all

• gatsby-node.js:1 Object.g
  /home/runner/work/posthog.com/posthog.com/.cache/compiled/gatsby-node.js:1:1 90197

• api-runner-node.js:487 runAPI
  [posthog.com]/[gatsby@4.25.9_@types+webpack@4.41.40_babel-eslint@10.1.0_esli nt@7.32.0__react-dom@18.3._21b413a261ed6ab8799d160716d386bb]/[gatsby]/src/ut ils/api-runner-node.js:487:16

not finished source and transform nodes - 30.900s
 ELIFECYCLE  Command failed with exit code 1.
Error: Process completed with exit code 1.

[pauldambra]

i'd be tempted to do a less is more pass as an edit step

i'm strongly supportive but also a lot of our folk don't have english as a first language and things like "grandfathered" are pretty ubiquitous and so defacto more clear (plus i think is a good example grandfathered despite being gendered is sliding into the grey area where someone who doesn't agree that changing language is valuable points at it as "going too far"

whereas things like blacklist or master/slave are much more defensible (from that perspective) they are more clear when replaced by deny or secondary

also wonder if it's better somewhere an agent will pick it up since they will generally be doing the first pass of any engineering content

[pauldambra]

(also, sorry if someone feels strongly about grandfathered. there is no one list of words that all people agree on and people's position and understanding is changing. it is more important that we are considering this than that we list out all the things)

[pauldambra]

Suggested change

	| `normal`, when describing users or behavior | `typical`, `default`, `common`, `expected` | Calling one group or behavior `normal` can imply others are abnormal. |
	| `suffers from`, `afflicted with` | `has`, `is` | Avoid pathologizing language, particularly in accessibility. For example, write `a user who is colorblind` instead of `a user who suffers from colorblindness`. |
	| Casual uses of `crazy`, `insane`, or `lame` | `unexpected`, `surprising`, `broken`, `high-volume`, `difficult`, `unhelpful` | Describe the behavior or impact instead. |

despite personally working pretty hard to avoid crazy (a very hard habit to break it turns out) I think it's not engineering specific and extends the list too much

whereas i can imagine someone where english isn't a first language not knowing the history of cripple

[pauldambra]

Suggested change

| `guys` | `team`, `folks`, `everyone`, `people` | Use a word that includes the whole group. |

i've also given up on "guys". while i use folks a lot of my female peers use "guys"

[haacked]

I think its worth including in the list though as a lot of folks might not realize there are good alternatives. After all, the list says "prefer" it doesn't say "you're a bad person if you say guys."

[pauldambra]

fair, my feeling was the list is too long but i also don't want to be the sole arbiter of what would be useful for people as prompts :)

[pauldambra]

Suggested change

| `normal`, when describing users or behavior | `typical`, `default`, `common`, `expected` | Calling one group or behavior `normal` can imply others are abnormal. |

while it is true that normal can be used as exclusionary language. i don't agree that saying normal and abnormal is automatically negative

("it would be abnormal to merge a PR without review outside of an interview" strikes me as a reasonable sentence. "it is normal to do 360 degree feedback during an offsite")

so with a less is more brush i wouldn't insist someone uses it but i wouldn't expect us to exclude it from use

not that saying we don't need to list it here means i wouldn't give a colleague feedback if i heard them describe a person as not normal or indeed in any other negative sense

[pauldambra]

Suggested change

	## Examples
	Prefer names that explain the rule or behavior:
	| Less clear | Better |
	|------------|--------|
	| `ip_whitelist` | `allowed_ip_addresses` |
	| `proxy_whitelist` | `trusted_proxy_ips` |
	| `property_blacklist` | `excluded_properties` |
	| `is_user_blacklisted` | `is_user_blocked` |
	| `master_database` | `primary_database` |
	| `slave_database` | `replica_database` |
	| `dummy_user` | `test_user` |
	| `sanity_check_query()` | `validate_query()` |
	User-facing copy should follow the same pattern:
	| Instead of | Use |
	|------------|-----|
	| `This domain is whitelisted.` | `This domain is allowed.` |
	| `This IP is blacklisted.` | `This IP is blocked.` |
	| `Run a sanity check before deploying.` | `Run a smoke test before deploying.` |
	| `This customer is grandfathered into the old plan.` | `This customer has retained access to the old plan.` |

i think the examples section follows a list of example 🙈

[pauldambra]

Suggested change

	- Request changes for new user-facing copy, public APIs, SDK options, config names, and docs.
	- Consider whether to request changes for new user-facing copy, public APIs, SDK options, config names, and docs where it is hard to change in a follow-up

given our guidance is that "Request changes" should be used sparingly i'm not sure we should be recommending it here

e.g. if something is easy to change in a follow-up then we can just comment "hey, we prefer blah to foo"

otherwise the same advice as usual would apply. if this was about SDK surface then it's harder to change than copy in the page and we should be more careful

[pauldambra]

we use grandfathered a lot in spoken and written comms

i think legacy is less clear, since it is an overloaded word in tech space

Suggested change

| `grandfathered` | `legacy`, `existing`, `retained access`, or explicit wording like "available on old plans" | Be clear about why something still applies. |

[haacked]

I still think its worth including in the list. I don't take this list to mean you are not allowed to use the word "grandfathered". It provides alternatives to consider. Some of those alternatives may be more precise. Considering the historical baggage of this term, its nice to be reminded of alternatives.

[pauldambra]

went through and suggested a bunch of edits to make my feedback more concrete

i am strongly supportive of a chunk of this, but we also need to consider that we are lucky that posthog has folk from a bunch of backgrounds and they don't all agree (and that having consideration for that is inclusive too :))

the longer and more specific the examples, the more likely we are to end up debating something from the list, which is generally not constructive

[haacked]

Always love effort to help us communicate better!

[haacked]

I think its worth including in the list though as a lot of folks might not realize there are good alternatives. After all, the list says "prefer" it doesn't say "you're a bad person if you say guys."

[haacked]

I still think its worth including in the list. I don't take this list to mean you are not allowed to use the word "grandfathered". It provides alternatives to consider. Some of those alternatives may be more precise. Considering the historical baggage of this term, its nice to be reminded of alternatives.