Update tone of CS docs to be more actionable and streamlined#16942
Open
danazou wants to merge 6 commits into
Open
Update tone of CS docs to be more actionable and streamlined#16942danazou wants to merge 6 commits into
danazou wants to merge 6 commits into
Conversation
added 6 commits
May 20, 2026 19:58
…atch handbook tone Strips preamble, cuts hedging, replaces corporate-speak with plain English, and collapses overlapping principles. Aligns voice with PostHog's style guide and the onboarding-conversations-playbook reference. ~50% word reduction across the three files. Generated-By: PostHog Code Task-Id: 3c12f58c-cdb0-41e4-8786-16d3eca067dd
…reasons Fixes remaining clinical/corporate phrasing flagged on review: "operational details", "maintain a pulse", "non-exhaustive", "footprint", "newer pattern", dangling "prioritize". Replaces with phrasing closer to how someone would actually say it. Generated-By: PostHog Code Task-Id: 3c12f58c-cdb0-41e4-8786-16d3eca067dd
renewals.md: fix "principals" typo, promote heading to H2, drop "win-win solution", restructure timing into bullets, tighten before-call guidance. handling-customer-issues.md: tighten opening, drop "Obviously" and "this capability", bulletize escalation criteria, preserve "PostHog human" wording. Generated-By: PostHog Code Task-Id: 3c12f58c-cdb0-41e4-8786-16d3eca067dd
Reorganizes getting-started-with-customers.md into a clearer timeline:
audit → reach out → first call → ongoing. Cuts preamble, drops the
incomplete customer-category framing, replaces corporate phrasing
("strategic partner", "surface", "gold standard", "target individuals",
"engagement level") with plainer language, and tightens hedged
constructions. Moves the legacy Teams add-on cost-saving tip to
health-checks.md where cost-saving guidance lives, dropping the
managed reverse proxy mention.
Generated-By: PostHog Code
Task-Id: 3c12f58c-cdb0-41e4-8786-16d3eca067dd
Cuts the 3-clause preamble, fixes typos ("you can to", "piplines",
"Persons Properties"), bulletizes the reverse proxy checks for
scanability, drops the data-pipeline origin story, and replaces
hedged or clinical phrasing ("It is beneficial to understand",
"exposes", "autocapture status", "misusing the product").
Generated-By: PostHog Code
Task-Id: 3c12f58c-cdb0-41e4-8786-16d3eca067dd
Resolved conflicts in two CS docs: - lifecycle-csm.md: kept my Stage 3 rewrite; folded master's new Slack channel bullet into Stage 2 with tone adjusted. - renewals.md: kept my rewrite; reorganized "Customers running out of credit early" under a new "Unique renewal cases" section; added master's two new subsections (expiring credits, irregular contracts) with tone aligned to the rest of the doc. health-checks.md auto-merged cleanly (my legacy Teams add-on snippet sat alongside master's new SDK health checks section). Generated-By: PostHog Code Task-Id: 3c12f58c-cdb0-41e4-8786-16d3eca067dd
Contributor
Deploy preview
|
Contributor
|
Vale prose linter → found 50 errors, 45 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!
|
| Line | Severity | Message | Rule |
|---|---|---|---|
| 17:178 | 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 |
| 36:49 | 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 |
| 56:73 | 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 |
| 60:54 | 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 |
| 66:4 | warning | Capitalize 'Session Replay' for PostHog's product. Use 'Session replay' for the general industry concept. | PostHogBase.ProductNames |
| 67:4 | warning | 'Cookieless' is a possible misspelling. | PostHogBase.Spelling |
| 83:68 | warning | 'underserved' is a possible misspelling. | PostHogBase.Spelling |
contents/handbook/cs-and-onboarding/customer-success.md — 3 errors, 1 warnings, 0 suggestions
| Line | Severity | Message | Rule |
|---|---|---|---|
| 7:28 | warning | 'CSMs' is a possible misspelling. | PostHogBase.Spelling |
| 13:98 | 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 |
| 21:71 | 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 |
| 32:96 | 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 |
contents/handbook/cs-and-onboarding/foundation-check.md — 6 errors, 6 warnings, 0 suggestions
| Line | Severity | Message | Rule |
|---|---|---|---|
| 7:98 | 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 |
| 15:16 | 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 |
| 16:23 | 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 |
| 26:8 | warning | Capitalize 'Session Replay' for PostHog's product. Use 'session replay' for the general industry concept. | PostHogBase.ProductNames |
| 27:8 | warning | Capitalize 'Session Replay' for PostHog's product. Use 'session replay' for the general industry concept. | PostHogBase.ProductNames |
| 28:28 | warning | Capitalize 'Session Replay' for PostHog's product. Use 'session replay' for the general industry concept. | PostHogBase.ProductNames |
| 42:137 | 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 |
| 61:4 | warning | 'Data pipelines for event notifications' heading should be in sentence case, and product names should be capitalized. | PostHogBase.SentenceCase |
| 61:4 | warning | Capitalize 'Data Pipelines' for PostHog's product. Use 'Data pipelines' for the general industry concept. | PostHogBase.ProductNames |
| 63:153 | 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 |
| 63:168 | warning | 'upsell' is a possible misspelling. | PostHogBase.Spelling |
| 67:103 | 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 |
contents/handbook/cs-and-onboarding/getting-started-with-customers.md — 21 errors, 5 warnings, 0 suggestions
| Line | Severity | Message | Rule |
|---|---|---|---|
| 7:134 | 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 |
| 43:5 | warning | 'Handover from Sales' heading should be in sentence case, and product names should be capitalized. | PostHogBase.SentenceCase |
| 53:17 | 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 |
| 60:19 | 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 |
| 60:142 | warning | 'CSMs' is a possible misspelling. | PostHogBase.Spelling |
| 61:18 | 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 |
| 67:29 | 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 |
| 68:25 | 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 |
| 71:37 | 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 |
| 72:115 | 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 |
| 78:32 | 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 |
| 88:111 | 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 |
| 92:69 | 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 |
| 96:53 | 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 |
| 112:96 | 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 |
| 112:253 | 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 |
| 118:197 | warning | Capitalize 'Product Analytics' for PostHog's product. Use 'product analytics' for the general industry concept. | PostHogBase.ProductNames |
| 119:161 | 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 |
| 125:32 | 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 |
| 145:87 | 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 |
| 162:19 | 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 |
| 163:13 | 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 |
| 164:15 | 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 |
| 168:155 | warning | 'MAUs' is a possible misspelling. | PostHogBase.Spelling |
| 170:52 | warning | 'upsell' is a possible misspelling. | PostHogBase.Spelling |
| 180:53 | 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 |
contents/handbook/cs-and-onboarding/handling-customer-issues.md — 6 errors, 1 warnings, 0 suggestions
| Line | Severity | Message | Rule |
|---|---|---|---|
| 21:300 | 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 |
| 25:180 | 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 |
| 33:185 | warning | 'mins' is a possible misspelling. | PostHogBase.Spelling |
| 33:247 | 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 |
| 35:53 | 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 |
| 46:51 | 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 |
| 48:282 | 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 |
contents/handbook/cs-and-onboarding/health-checks.md — 0 errors, 24 warnings, 0 suggestions
| Line | Severity | Message | Rule |
|---|---|---|---|
| 31:767 | warning | 'benefitting' is a possible misspelling. | PostHogBase.Spelling |
| 33:16 | warning | 'benefitting' is a possible misspelling. | PostHogBase.Spelling |
| 35:5 | warning | 'Legacy Teams add-on' heading should be in sentence case, and product names should be capitalized. | PostHogBase.SentenceCase |
| 42:5 | warning | 'Session replay targeting' heading should be in sentence case, and product names should be capitalized. | PostHogBase.SentenceCase |
| 42:5 | warning | Capitalize 'Session Replay' for PostHog's product. Use 'Session replay' for the general industry concept. | PostHogBase.ProductNames |
| 44:6 | warning | Capitalize 'Session Replay' for PostHog's product. Use 'Session replay' for the general industry concept. | PostHogBase.ProductNames |
| 46:19 | warning | Capitalize 'Session Replay' for PostHog's product. Use 'Session replay' for the general industry concept. | PostHogBase.ProductNames |
| 46:76 | warning | Capitalize 'Session Replay' for PostHog's product. Use 'session replay' for the general industry concept. | PostHogBase.ProductNames |
| 54:63 | warning | 'touchpoint' is a possible misspelling. | PostHogBase.Spelling |
| 64:13 | warning | 'groupidentify' is a possible misspelling. | PostHogBase.Spelling |
| 66:158 | warning | 'groupidentify' is a possible misspelling. | PostHogBase.Spelling |
| 70:24 | warning | 'groupidentify' is a possible misspelling. | PostHogBase.Spelling |
| 89:5 | warning | 'Calling posthog.reset() before identifying the user' heading should be in sentence case, and product names should be capitalized. | PostHogBase.SentenceCase |
| 89:13 | warning | Use 'PostHog' instead of 'posthog'. | Vale.Terms |
| 101:5 | warning | 'Cookieless' is a possible misspelling. | PostHogBase.Spelling |
| 103:296 | warning | 'initiatlize' is a possible misspelling. | PostHogBase.Spelling |
| 103:321 | warning | 'cookieless' is a possible misspelling. | PostHogBase.Spelling |
| 116:209 | warning | 'initializer' is a possible misspelling. | PostHogBase.Spelling |
| 116:241 | warning | 'cookieless' is a possible misspelling. | PostHogBase.Spelling |
| 116:360 | warning | 'cookieless' is a possible misspelling. | PostHogBase.Spelling |
| 116:397 | warning | 'Cookieless' is a possible misspelling. | PostHogBase.Spelling |
| 118:1 | warning | 'Cookieless' is a possible misspelling. | PostHogBase.Spelling |
| 118:85 | warning | 'cookieless' is a possible misspelling. | PostHogBase.Spelling |
| 120:8 | warning | Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. | PostHogBase.ProductNames |
contents/handbook/cs-and-onboarding/lifecycle-csm.md — 3 errors, 2 warnings, 0 suggestions
| Line | Severity | Message | Rule |
|---|---|---|---|
| 19:234 | 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 |
| 21:185 | warning | Capitalize 'Error Tracking' for PostHog's product. Use 'error tracking' for the general industry concept. | PostHogBase.ProductNames |
| 22:182 | 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 |
| 24:56 | warning | 'touchpoint' is a possible misspelling. | PostHogBase.Spelling |
| 35:104 | 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 |
contents/handbook/cs-and-onboarding/renewals.md — 7 errors, 3 warnings, 0 suggestions
| Line | Severity | Message | Rule |
|---|---|---|---|
| 11:148 | 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 |
| 11:211 | warning | 'upsell' is a possible misspelling. | PostHogBase.Spelling |
| 22: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 |
| 30:136 | 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 |
| 40:118 | 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 |
| 40:171 | warning | Use the Oxford comma before 'and' or 'or' in a list of three or more items. | PostHogBase.OxfordComma |
| 42:159 | 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 |
| 50:98 | warning | 'Quotehog' is a possible misspelling. | PostHogBase.Spelling |
| 52:45 | 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 |
| 54:166 | 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 |
danazou
changed the title
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
1 participant
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.
Some of CS handbook docs were reading too corporate / heavy – lots of hedging, preamble, and "leveraging" language. This cleans them up to be more direct and actionable.
What changed
getting-started-with-customers.mdalso got a restructure – the old layout bounced between audit, intro, and prioritization in no particular order. Reorganized into a clear flow: audit → reach out → first call → ongoing.getting-started-with-customers.mdtohealth-checks.mdsince that's where cost-saving guidance lives.Word count dropped roughly 50% across the rewritten docs. Operational content (links, tool references, checklists) all preserved.
Files touched
customer-success.mdlifecycle-csm.mdchurn-reasons.mdrenewals.mdhandling-customer-issues.mdgetting-started-with-customers.md(also restructured)health-checks.md(small addition only — the moved snippet, no rewrite)foundation-check.mdTo check
PrivateLink,TeamMember) render correctlyCreated with PostHog Code