From a8fb64e759655a899e0e9e5395c519b4eeddeabb Mon Sep 17 00:00:00 2001 From: David Longworth Date: Wed, 29 Apr 2026 14:17:42 +0100 Subject: [PATCH 01/22] make it scannable --- .../src/docs/public/copy/styleguide.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/packages/stacks-docs-next/src/docs/public/copy/styleguide.md b/packages/stacks-docs-next/src/docs/public/copy/styleguide.md index b3255f38a9..8e70dc4c2d 100644 --- a/packages/stacks-docs-next/src/docs/public/copy/styleguide.md +++ b/packages/stacks-docs-next/src/docs/public/copy/styleguide.md @@ -1,5 +1,5 @@ --- -updated: 2025-12-11 +updated: 2026-04-29 --- + + {data?.active?.title} - Design System + + +

{data?.active?.title}

{data?.active?.description}

From 7ba1b8354e5dd82dcfc5b8aa73906e88d5cd9fa0 Mon Sep 17 00:00:00 2001 From: David Longworth Date: Wed, 29 Apr 2026 14:47:36 +0100 Subject: [PATCH 05/22] update slug to match title --- packages/stacks-docs-next/src/structure.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/stacks-docs-next/src/structure.yaml b/packages/stacks-docs-next/src/structure.yaml index 3f5c279c2f..c73aff1288 100644 --- a/packages/stacks-docs-next/src/structure.yaml +++ b/packages/stacks-docs-next/src/structure.yaml @@ -69,7 +69,7 @@ navigation: private: true - title: "Tone" - slug: "voice" + slug: "tone" image: "/images/heros/voice.svg" private: true From e45e08ef770084af4c85d6c4d9c6e270f93f3beb Mon Sep 17 00:00:00 2001 From: David Longworth Date: Wed, 29 Apr 2026 15:17:08 +0100 Subject: [PATCH 06/22] community copy --- packages/stacks-docs-next/src/docs/private | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/stacks-docs-next/src/docs/private b/packages/stacks-docs-next/src/docs/private index a1fdedd61e..09f4f29553 160000 --- a/packages/stacks-docs-next/src/docs/private +++ b/packages/stacks-docs-next/src/docs/private @@ -1 +1 @@ -Subproject commit a1fdedd61e1370dd4147cf335e9919f05103f8ce +Subproject commit 09f4f295537de5aa99beedbecdfaaac81521eee2 From 4add87c767f61e56d04f38000e77e3646c68ba15 Mon Sep 17 00:00:00 2001 From: David Longworth Date: Wed, 6 May 2026 13:46:37 +0100 Subject: [PATCH 07/22] catregory page title --- packages/stacks-docs/src/routes/[category]/+page.svelte | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/packages/stacks-docs/src/routes/[category]/+page.svelte b/packages/stacks-docs/src/routes/[category]/+page.svelte index bc6c92867b..f8324e51ee 100644 --- a/packages/stacks-docs/src/routes/[category]/+page.svelte +++ b/packages/stacks-docs/src/routes/[category]/+page.svelte @@ -4,6 +4,11 @@ let { data }: { data: App.PageData } = $props(); + + {data?.active?.title} - Design System + + +

{data?.active?.title}

{data?.active?.description}

From 8cc560000edae82484f4626c8fea966684edfcda Mon Sep 17 00:00:00 2001 From: David Longworth Date: Fri, 8 May 2026 11:17:25 +0100 Subject: [PATCH 08/22] add heros --- packages/stacks-docs/src/structure.yaml | 9 +++++---- packages/stacks-docs/static/images/heros/audiences.svg | 1 + .../stacks-docs/static/images/heros/language_grammar.svg | 1 + packages/stacks-docs/static/images/heros/terminology.svg | 1 + packages/stacks-docs/static/images/heros/tone.svg | 1 + 5 files changed, 9 insertions(+), 4 deletions(-) create mode 100644 packages/stacks-docs/static/images/heros/audiences.svg create mode 100644 packages/stacks-docs/static/images/heros/language_grammar.svg create mode 100644 packages/stacks-docs/static/images/heros/terminology.svg create mode 100644 packages/stacks-docs/static/images/heros/tone.svg diff --git a/packages/stacks-docs/src/structure.yaml b/packages/stacks-docs/src/structure.yaml index f7cf50036d..9ee7439a2d 100644 --- a/packages/stacks-docs/src/structure.yaml +++ b/packages/stacks-docs/src/structure.yaml @@ -58,6 +58,7 @@ navigation: - title: "Settings & preferences" slug: "settings" + - title: "Community" slug: "community" description: "How to consider community when working on Stack Overflow." @@ -65,22 +66,22 @@ navigation: items: - title: "Audiences" slug: "audiences" - image: "/images/heros/voice.svg" + image: "/images/heros/audiences.svg" private: true - title: "Tone" slug: "tone" - image: "/images/heros/voice.svg" + image: "/images/heros/tone.svg" private: true - title: "Language & grammar" slug: "language" - image: "/images/heros/styleguide.svg" + image: "/images/heros/language_grammar.svg" private: true - title: "Terminology" slug: "terminology" - image: "/images/heros/naming.svg" + image: "/images/heros/terminology.svg" private: true - title: "Product" diff --git a/packages/stacks-docs/static/images/heros/audiences.svg b/packages/stacks-docs/static/images/heros/audiences.svg new file mode 100644 index 0000000000..36a80477bc --- /dev/null +++ b/packages/stacks-docs/static/images/heros/audiences.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/packages/stacks-docs/static/images/heros/language_grammar.svg b/packages/stacks-docs/static/images/heros/language_grammar.svg new file mode 100644 index 0000000000..1229e0e93a --- /dev/null +++ b/packages/stacks-docs/static/images/heros/language_grammar.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/packages/stacks-docs/static/images/heros/terminology.svg b/packages/stacks-docs/static/images/heros/terminology.svg new file mode 100644 index 0000000000..6a2ebf87c8 --- /dev/null +++ b/packages/stacks-docs/static/images/heros/terminology.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/packages/stacks-docs/static/images/heros/tone.svg b/packages/stacks-docs/static/images/heros/tone.svg new file mode 100644 index 0000000000..fdc15ceebd --- /dev/null +++ b/packages/stacks-docs/static/images/heros/tone.svg @@ -0,0 +1 @@ + \ No newline at end of file From 98b1526908ec744d6f64b119facf3b01c2d59514 Mon Sep 17 00:00:00 2001 From: David Longworth Date: Tue, 19 May 2026 15:22:25 +0100 Subject: [PATCH 09/22] homepage updates remove static icons, update the styles --- .../src/lib/assets/icons/brand.svg | 1 - .../src/lib/assets/icons/copywriting.svg | 1 - .../src/lib/assets/icons/email.svg | 1 - .../src/lib/assets/icons/handbook.svg | 3 - .../src/lib/assets/icons/product.svg | 1 - .../src/lib/assets/icons/resources.svg | 1 - packages/stacks-docs/src/routes/+page.svelte | 68 ++++++++++--------- 7 files changed, 37 insertions(+), 39 deletions(-) delete mode 100644 packages/stacks-docs/src/lib/assets/icons/brand.svg delete mode 100644 packages/stacks-docs/src/lib/assets/icons/copywriting.svg delete mode 100644 packages/stacks-docs/src/lib/assets/icons/email.svg delete mode 100644 packages/stacks-docs/src/lib/assets/icons/handbook.svg delete mode 100644 packages/stacks-docs/src/lib/assets/icons/product.svg delete mode 100644 packages/stacks-docs/src/lib/assets/icons/resources.svg diff --git a/packages/stacks-docs/src/lib/assets/icons/brand.svg b/packages/stacks-docs/src/lib/assets/icons/brand.svg deleted file mode 100644 index c71d8c75e0..0000000000 --- a/packages/stacks-docs/src/lib/assets/icons/brand.svg +++ /dev/null @@ -1 +0,0 @@ - diff --git a/packages/stacks-docs/src/lib/assets/icons/copywriting.svg b/packages/stacks-docs/src/lib/assets/icons/copywriting.svg deleted file mode 100644 index 17f912eccf..0000000000 --- a/packages/stacks-docs/src/lib/assets/icons/copywriting.svg +++ /dev/null @@ -1 +0,0 @@ - diff --git a/packages/stacks-docs/src/lib/assets/icons/email.svg b/packages/stacks-docs/src/lib/assets/icons/email.svg deleted file mode 100644 index ad4f135145..0000000000 --- a/packages/stacks-docs/src/lib/assets/icons/email.svg +++ /dev/null @@ -1 +0,0 @@ - diff --git a/packages/stacks-docs/src/lib/assets/icons/handbook.svg b/packages/stacks-docs/src/lib/assets/icons/handbook.svg deleted file mode 100644 index 8746e36738..0000000000 --- a/packages/stacks-docs/src/lib/assets/icons/handbook.svg +++ /dev/null @@ -1,3 +0,0 @@ - - - diff --git a/packages/stacks-docs/src/lib/assets/icons/product.svg b/packages/stacks-docs/src/lib/assets/icons/product.svg deleted file mode 100644 index 70272a431d..0000000000 --- a/packages/stacks-docs/src/lib/assets/icons/product.svg +++ /dev/null @@ -1 +0,0 @@ - diff --git a/packages/stacks-docs/src/lib/assets/icons/resources.svg b/packages/stacks-docs/src/lib/assets/icons/resources.svg deleted file mode 100644 index 8e5a1b88c5..0000000000 --- a/packages/stacks-docs/src/lib/assets/icons/resources.svg +++ /dev/null @@ -1 +0,0 @@ - diff --git a/packages/stacks-docs/src/routes/+page.svelte b/packages/stacks-docs/src/routes/+page.svelte index 840ceff791..94114ce5d4 100644 --- a/packages/stacks-docs/src/routes/+page.svelte +++ b/packages/stacks-docs/src/routes/+page.svelte @@ -1,24 +1,35 @@ @@ -38,8 +49,8 @@ -
-
+
+
v{__APP_VERSION__} @@ -49,29 +60,24 @@

Stacks

-

+

The Stack Overflow Design System – resources for product designers, developers, marketers and everyone who works with Stack Overflow.

{#each data.structure?.navigation as category (category.slug)} - -

{category.title}

+
+

{category.title}

{category.description}

 {/each} - - - -

Looking for the previous version of Stacks?

-

If you are working on a classic experience you can visit the v2 documentation.

-
+ + +

Looking for the previous version of Stacks? Go to the classic v2 documentation.

+
From e0add6187d17640d1e0cd11775d98018e273d6cf Mon Sep 17 00:00:00 2001 From: David Longworth Date: Tue, 19 May 2026 15:37:55 +0100 Subject: [PATCH 10/22] responsive category page h1 --- packages/stacks-docs/src/routes/[category]/+page.svelte | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/packages/stacks-docs/src/routes/[category]/+page.svelte b/packages/stacks-docs/src/routes/[category]/+page.svelte index f8324e51ee..90cb246ac2 100644 --- a/packages/stacks-docs/src/routes/[category]/+page.svelte +++ b/packages/stacks-docs/src/routes/[category]/+page.svelte @@ -10,7 +10,7 @@
-

{data?.active?.title}

+

{data?.active?.title}

{data?.active?.description}

{#each data?.active?.items as subsection (subsection.slug)} @@ -28,3 +28,9 @@ {/if} {/each}
+ + From 31310d8865d600a0b879969d4d826ba6a40e8613 Mon Sep 17 00:00:00 2001 From: David Longworth Date: Tue, 19 May 2026 15:38:25 +0100 Subject: [PATCH 11/22] docs page large viewport adjustments --- .../[[section]]/[subsection]/+page.svelte | 86 +++++++++---------- 1 file changed, 43 insertions(+), 43 deletions(-) diff --git a/packages/stacks-docs/src/routes/[category]/[[section]]/[subsection]/+page.svelte b/packages/stacks-docs/src/routes/[category]/[[section]]/[subsection]/+page.svelte index d005e2b5b6..5e26e3c260 100644 --- a/packages/stacks-docs/src/routes/[category]/[[section]]/[subsection]/+page.svelte +++ b/packages/stacks-docs/src/routes/[category]/[[section]]/[subsection]/+page.svelte @@ -28,54 +28,54 @@ +
+ -
-
-
- +
+ {#if data?.metadata?.js} + + + JavaScript + + {/if} -
- {#if data?.metadata?.js} - - - JavaScript - - {/if} + {#if data?.metadata?.figma} + + + Figma + + {/if} - {#if data?.metadata?.figma} - - - Figma - - {/if} + {#if data?.metadata?.svelte} + + + Svelte + + {/if} - {#if data?.metadata?.svelte} - - - Svelte - - {/if} + {#if data.filename} + + + Edit + + {/if} +
+
- {#if data.filename} - - - Edit - - {/if} -
-
+
+
{#if data?.metadata?.updated} From 5c51db098ddc545c5f36ac382c0b9331c83738db Mon Sep 17 00:00:00 2001 From: David Longworth Date: Tue, 19 May 2026 15:39:18 +0100 Subject: [PATCH 12/22] update icons --- package-lock.json | 139 ++++++++++++++++++++++++++++------------------ package.json | 2 +- 2 files changed, 85 insertions(+), 56 deletions(-) diff --git a/package-lock.json b/package-lock.json index 9305c6197b..f7dc1d8609 100644 --- a/package-lock.json +++ b/package-lock.json @@ -18,7 +18,7 @@ "@rollup/plugin-commonjs": "^26.0.1", "@rollup/plugin-replace": "^6.0.3", "@stackoverflow/prettier-config": "^1.0.0", - "@stackoverflow/stacks-icons": "^7.0.0-beta.21", + "@stackoverflow/stacks-icons": "^7.0.0-beta.24", "@stackoverflow/stacks-icons-legacy": "npm:@stackoverflow/stacks-icons@^6.9.0", "@storybook/addon-a11y": "^10.1.11", "@storybook/addon-docs": "^10.1.11", @@ -1402,7 +1402,7 @@ }, "node_modules/@jridgewell/source-map": { "version": "0.3.11", - "devOptional": true, + "dev": true, "license": "MIT", "dependencies": { "@jridgewell/gen-mapping": "^0.3.5", @@ -1822,6 +1822,7 @@ "cpu": [ "arm" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -1835,6 +1836,7 @@ "cpu": [ "arm64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -1846,6 +1848,7 @@ "cpu": [ "arm64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -1859,6 +1862,7 @@ "cpu": [ "x64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -1872,6 +1876,7 @@ "cpu": [ "arm64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -1885,6 +1890,7 @@ "cpu": [ "x64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -1898,9 +1904,7 @@ "cpu": [ "arm" ], - "libc": [ - "glibc" - ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -1914,9 +1918,7 @@ "cpu": [ "arm" ], - "libc": [ - "musl" - ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -1930,9 +1932,7 @@ "cpu": [ "arm64" ], - "libc": [ - "glibc" - ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -1946,9 +1946,7 @@ "cpu": [ "arm64" ], - "libc": [ - "musl" - ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -1962,9 +1960,7 @@ "cpu": [ "loong64" ], - "libc": [ - "glibc" - ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -1978,9 +1974,7 @@ "cpu": [ "ppc64" ], - "libc": [ - "glibc" - ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -1994,9 +1988,7 @@ "cpu": [ "riscv64" ], - "libc": [ - "glibc" - ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -2010,9 +2002,7 @@ "cpu": [ "riscv64" ], - "libc": [ - "musl" - ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -2026,9 +2016,7 @@ "cpu": [ "s390x" ], - "libc": [ - "glibc" - ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -2042,9 +2030,7 @@ "cpu": [ "x64" ], - "libc": [ - "glibc" - ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -2058,9 +2044,7 @@ "cpu": [ "x64" ], - "libc": [ - "musl" - ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -2074,6 +2058,7 @@ "cpu": [ "arm64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -2087,6 +2072,7 @@ "cpu": [ "arm64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -2100,6 +2086,7 @@ "cpu": [ "ia32" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -2113,6 +2100,7 @@ "cpu": [ "x64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -2126,6 +2114,7 @@ "cpu": [ "x64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -2222,11 +2211,15 @@ } }, "node_modules/@stackoverflow/stacks-editor/node_modules/@stackoverflow/stacks-icons": { - "version": "6.7.0", + "version": "6.9.0", + "resolved": "https://registry.npmjs.org/@stackoverflow/stacks-icons/-/stacks-icons-6.9.0.tgz", + "integrity": "sha512-SFlcnSrH0b0/SsDBhCypYANyUwJs8hyuZzpo53l4iUUm30FGRbBWNfcaWwBW/skRjpHvlFYaUXwt66ZI6zT+lg==", "license": "MIT" }, "node_modules/@stackoverflow/stacks-icons": { - "version": "7.0.0-beta.23", + "version": "7.0.0-beta.24", + "resolved": "https://registry.npmjs.org/@stackoverflow/stacks-icons/-/stacks-icons-7.0.0-beta.24.tgz", + "integrity": "sha512-YNLn98BF1gcncorpsvIgle3w1Ez/RtNcL24CVquOVW1uSF4kt3GnH6b3aTeeMzX76uLaQmwEQEedWP0aKBcG2g==", "license": "Apache-2.0" }, "node_modules/@stackoverflow/stacks-icons-legacy": { @@ -3040,7 +3033,7 @@ }, "node_modules/@types/node": { "version": "24.9.1", - "devOptional": true, + "dev": true, "license": "MIT", "dependencies": { "undici-types": "~7.16.0" @@ -4581,7 +4574,7 @@ }, "node_modules/buffer-from": { "version": "1.1.2", - "devOptional": true, + "dev": true, "license": "MIT" }, "node_modules/bundle-name": { @@ -5206,7 +5199,7 @@ }, "node_modules/copy-anything": { "version": "2.0.6", - "devOptional": true, + "dev": true, "license": "MIT", "peer": true, "dependencies": { @@ -6701,6 +6694,7 @@ }, "node_modules/fsevents": { "version": "2.3.3", + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -6934,7 +6928,7 @@ }, "node_modules/graceful-fs": { "version": "4.2.11", - "devOptional": true, + "dev": true, "license": "ISC" }, "node_modules/has-flag": { @@ -7350,6 +7344,7 @@ }, "node_modules/image-size": { "version": "0.5.5", + "dev": true, "license": "MIT", "optional": true, "peer": true, @@ -7758,7 +7753,7 @@ }, "node_modules/is-what": { "version": "3.14.1", - "devOptional": true, + "dev": true, "license": "MIT", "peer": true }, @@ -7881,7 +7876,7 @@ }, "node_modules/jiti": { "version": "2.6.1", - "devOptional": true, + "dev": true, "license": "MIT", "bin": { "jiti": "lib/jiti-cli.mjs" @@ -8094,7 +8089,7 @@ }, "node_modules/less": { "version": "4.5.1", - "devOptional": true, + "dev": true, "hasInstallScript": true, "license": "Apache-2.0", "peer": true, @@ -8146,6 +8141,7 @@ }, "node_modules/less/node_modules/errno": { "version": "0.1.8", + "dev": true, "license": "MIT", "optional": true, "peer": true, @@ -8158,6 +8154,7 @@ }, "node_modules/less/node_modules/make-dir": { "version": "2.1.0", + "dev": true, "license": "MIT", "optional": true, "peer": true, @@ -8171,6 +8168,7 @@ }, "node_modules/less/node_modules/mime": { "version": "1.6.0", + "dev": true, "license": "MIT", "optional": true, "peer": true, @@ -8183,6 +8181,7 @@ }, "node_modules/less/node_modules/semver": { "version": "5.7.2", + "dev": true, "license": "ISC", "optional": true, "peer": true, @@ -8192,6 +8191,7 @@ }, "node_modules/less/node_modules/source-map": { "version": "0.6.1", + "dev": true, "license": "BSD-3-Clause", "optional": true, "peer": true, @@ -8757,6 +8757,7 @@ }, "node_modules/needle": { "version": "3.3.1", + "dev": true, "license": "MIT", "optional": true, "peer": true, @@ -8773,6 +8774,7 @@ }, "node_modules/needle/node_modules/iconv-lite": { "version": "0.6.3", + "dev": true, "license": "MIT", "optional": true, "peer": true, @@ -9159,7 +9161,7 @@ }, "node_modules/parse-node-version": { "version": "1.0.1", - "devOptional": true, + "dev": true, "license": "MIT", "peer": true, "engines": { @@ -9271,7 +9273,7 @@ }, "node_modules/pify": { "version": "4.0.1", - "devOptional": true, + "dev": true, "license": "MIT", "engines": { "node": ">=6" @@ -10260,6 +10262,7 @@ }, "node_modules/prr": { "version": "1.0.1", + "dev": true, "license": "MIT", "optional": true, "peer": true @@ -11694,12 +11697,12 @@ }, "node_modules/safer-buffer": { "version": "2.1.2", - "devOptional": true, + "dev": true, "license": "MIT" }, "node_modules/sax": { "version": "1.4.1", - "devOptional": true, + "dev": true, "license": "ISC" }, "node_modules/scheduler": { @@ -12029,7 +12032,7 @@ }, "node_modules/source-map-support": { "version": "0.5.21", - "devOptional": true, + "dev": true, "license": "MIT", "dependencies": { "buffer-from": "^1.0.0", @@ -12038,7 +12041,7 @@ }, "node_modules/source-map-support/node_modules/source-map": { "version": "0.6.1", - "devOptional": true, + "dev": true, "license": "BSD-3-Clause", "engines": { "node": ">=0.10.0" @@ -12986,7 +12989,7 @@ }, "node_modules/terser": { "version": "5.44.0", - "devOptional": true, + "dev": true, "license": "BSD-2-Clause", "dependencies": { "@jridgewell/source-map": "^0.3.3", @@ -13036,7 +13039,7 @@ }, "node_modules/terser/node_modules/commander": { "version": "2.20.3", - "devOptional": true, + "dev": true, "license": "MIT" }, "node_modules/text-decoder": { @@ -13190,7 +13193,7 @@ }, "node_modules/tslib": { "version": "2.8.1", - "devOptional": true, + "dev": true, "license": "0BSD" }, "node_modules/tsscmp": { @@ -13257,7 +13260,7 @@ }, "node_modules/typescript": { "version": "5.9.3", - "devOptional": true, + "dev": true, "license": "Apache-2.0", "bin": { "tsc": "bin/tsc", @@ -13328,7 +13331,7 @@ }, "node_modules/undici-types": { "version": "7.16.0", - "devOptional": true, + "dev": true, "license": "MIT" }, "node_modules/unicorn-magic": { @@ -13673,6 +13676,7 @@ "cpu": [ "ppc64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -13689,6 +13693,7 @@ "cpu": [ "arm" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -13705,6 +13710,7 @@ "cpu": [ "arm64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -13721,6 +13727,7 @@ "cpu": [ "x64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -13735,6 +13742,7 @@ "cpu": [ "arm64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -13751,6 +13759,7 @@ "cpu": [ "x64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -13767,6 +13776,7 @@ "cpu": [ "arm64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -13783,6 +13793,7 @@ "cpu": [ "x64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -13799,6 +13810,7 @@ "cpu": [ "arm" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -13815,6 +13827,7 @@ "cpu": [ "arm64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -13831,6 +13844,7 @@ "cpu": [ "ia32" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -13847,6 +13861,7 @@ "cpu": [ "loong64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -13863,6 +13878,7 @@ "cpu": [ "mips64el" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -13879,6 +13895,7 @@ "cpu": [ "ppc64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -13895,6 +13912,7 @@ "cpu": [ "riscv64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -13911,6 +13929,7 @@ "cpu": [ "s390x" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -13927,6 +13946,7 @@ "cpu": [ "x64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -13943,6 +13963,7 @@ "cpu": [ "arm64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -13959,6 +13980,7 @@ "cpu": [ "x64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -13975,6 +13997,7 @@ "cpu": [ "arm64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -13991,6 +14014,7 @@ "cpu": [ "x64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -14007,6 +14031,7 @@ "cpu": [ "arm64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -14023,6 +14048,7 @@ "cpu": [ "x64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -14039,6 +14065,7 @@ "cpu": [ "arm64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -14055,6 +14082,7 @@ "cpu": [ "ia32" ], + "dev": true, "license": "MIT", "optional": true, "os": [ @@ -14071,6 +14099,7 @@ "cpu": [ "x64" ], + "dev": true, "license": "MIT", "optional": true, "os": [ diff --git a/package.json b/package.json index a17ce17e99..adf27e4d07 100644 --- a/package.json +++ b/package.json @@ -28,7 +28,7 @@ "@rollup/plugin-commonjs": "^26.0.1", "@rollup/plugin-replace": "^6.0.3", "@stackoverflow/prettier-config": "^1.0.0", - "@stackoverflow/stacks-icons": "^7.0.0-beta.21", + "@stackoverflow/stacks-icons": "^7.0.0-beta.24", "@stackoverflow/stacks-icons-legacy": "npm:@stackoverflow/stacks-icons@^6.9.0", "@storybook/addon-a11y": "^10.1.11", "@storybook/addon-docs": "^10.1.11", From 0d34e1f90a07296fcb3aa5d4f1b1205dd83c072e Mon Sep 17 00:00:00 2001 From: David Longworth Date: Tue, 19 May 2026 15:39:36 +0100 Subject: [PATCH 13/22] wip content --- .../src/docs/public/community/audiences.md | 67 ++++++ .../src/docs/public/community/language.md | 218 ++++++++++++++++++ .../src/docs/public/community/terminology.md | 78 +++++++ .../src/docs/public/community/tone.md | 184 +++++++++++++++ packages/stacks-docs/src/structure.yaml | 7 +- 5 files changed, 548 insertions(+), 6 deletions(-) create mode 100644 packages/stacks-docs/src/docs/public/community/audiences.md create mode 100644 packages/stacks-docs/src/docs/public/community/language.md create mode 100644 packages/stacks-docs/src/docs/public/community/terminology.md create mode 100644 packages/stacks-docs/src/docs/public/community/tone.md diff --git a/packages/stacks-docs/src/docs/public/community/audiences.md b/packages/stacks-docs/src/docs/public/community/audiences.md new file mode 100644 index 0000000000..4602f42fbb --- /dev/null +++ b/packages/stacks-docs/src/docs/public/community/audiences.md @@ -0,0 +1,67 @@ +--- +title: "Audiences" +description: "The three groups you’ll be writing for on Meta — and how to tailor calls-to-action for each." +updated: 2026-04-29 +--- + + + +Meta sites are the backbone of Stack Overflow’s Public Platforms – a space where the community discusses how the site should work, raises issues, and influences decisions. For sites with their own domain you can find them at `meta.` + the domain, e.g. meta.stackoverflow.com and subdomain sites you can find them at `sitename.meta.`stackexchange.com e.g., math.meta.stackexchange.com + +## Introduction + +Writing on Meta sites involves addressing a few different audiences, sometimes in a single post. At this time in the company’s history, one task before us is rebuilding trust with a technical, opinionated, and change-averse user base. At the same time, we must inform and entice new or less-seasoned users who are looking to possibly do more. We must also re-engage users who have shifted from being contributors to more passive readers over time. We need to speak to all groups. Communications authors may choose to make any of these groups their primary audience, but we must remain conscious of all groups when writing to have maximum effectiveness. + +For the purposes of these guidelines, we’re roughly dividing the people you might need to communicate with into three somewhat arbitrary groups, whose boundaries might be somewhat fuzzy on occasion. + +## Seasoned users + +**Seasoned users** are perhaps slow to trust or get excited about something that is new, or a shift from “the way things have always been.” Every good public communication is an opportunity to earn their confidence and build trust, and every bad public communication risks confirming their suspicions and fueling skepticism. The goal isn’t just to inform, but to convey that the company understands their craft, respects their investment of time on the platform, and values their opinions. Empathy is key: recognize the disruption that platform changes may cause for seasoned users. When speaking to seasoned users, write as a peer seeking collaboration. Use language that minimizes the emotional distance between you and the reader. **Calls-to-action are for collaboration and feedback.** + +This group includes the traditional, somewhat loosely-defined roles we often refer to in product development: active/engaged user, contributor, curator, leader, moderator. When crafting communication focused on actions some of these groups perform (or that we hope they perform), it’s important to understand the role being targeted. But note that there is much overlap in those roles, and an individual user’s actions may fit into multiple roles. + + + +

Don’t

+

“We’ve built this new tool.”

+ + +

Do

+

“We understand the pain points you have with the existing workflow. To address X and Y, our proposed solutions are A and B.”

+ + + +## Newer users + +**Newer users** need clear, reassuring, and instructive communication. Fostering a sense of inclusion within the community is key since that’s our big differentiator. The tone can be slightly more enthusiastic and focus on immediate benefits and quick wins. **Calls-to-action should be grounded in the options available and what they can do now/today.** + + + +

Don’t

+

“These restrictions have been in place since X, with the intention of preventing Y, and our data has shown that Z, so we’re making the decision to temporarily lower the restrictions.”

+ + +

Do

+

“We’ve lowered these restrictions, and are excited to see a much larger proportion of the community using X!”

+ + + +## Passively engaged users + +**Passively engaged users** (experienced users who have drifted away) bring opportunity for reengagement through general messaging and also targeted messaging. This is a group we have historical data about (as opposed to new users) and so they may be prime for targeted messaging. Communications aimed at this group should focus on the additions that work toward a stronger future, and on the value of new improvements they may not be aware of. **Calls-to-action are “try it out” and asking for feedback, focusing on any kind of engagement** (since that is what we want from this group). + + + +

Don’t

+

“X has a new face, and we hope to see engagement from newcomers increase in the coming months.”

+ + +

Do

+

“We’re excited to get your feedback on this new and improved version of X, which we hope addresses many of the longstanding concerns raised in prior posts over the years.”

+ + diff --git a/packages/stacks-docs/src/docs/public/community/language.md b/packages/stacks-docs/src/docs/public/community/language.md new file mode 100644 index 0000000000..8a581969c9 --- /dev/null +++ b/packages/stacks-docs/src/docs/public/community/language.md @@ -0,0 +1,218 @@ +--- +title: "Language & grammar" +description: "Grammatical guidelines for Meta posts that reduce confusion and improve consistency across teams." +updated: 2026-04-29 +--- + + + +Language and grammar aren’t just mechanical decisions: they should structure clarity, remove ambiguity, and make messages readable for both novice and experienced users. Our grammatical guidelines should reduce confusion and improve consistency in communication from across teams. + + +

The public Style guide covers brand-wide grammar and mechanics. The guidance below is specific to Meta posts.

+ + +## Prefer active voice over passive voice + +**Why:** passive voice hides responsibility and feels evasive, and is strongly associated with “bad communication” examples. + +- While it’s generally best to avoid the passive voice, in certain situations it helps you sound softer without adding too many words. +- You can also occasionally use the passive voice to avoid excessively referring to yourself or Stack Overflow — as long as you’ve primarily used active voice (to make it clear we’re taking ownership of our actions). +- However, default to active voice in most cases. + + + +

Don’t

+

“Comment spoilers have been updated.”

+ + +

Do

+

“We updated comment spoilers to fix keyboard accessibility.”

+ + + +### Exceptions — when passive can vary the tone + +Passive voice can be acceptable to soften an announcement, or to avoid excessive self-reference, as long as active voice dominates. + + + +

Active (strong / direct)

+
    +
  • “We are delaying the release.”
    • +
  • “We decided not to move forward with further development.”
    • +
+ + +

Passive (softened when needed)

+
    +
  • “The release is being delayed.”
    • +
  • “A decision has been reached and development will not be moving forward.”
    • +
+ + + + + +

Active (strong first person)

+
    +
  • “Our team conducted a research study over six months.”
    • +
  • “We obscure your personal data to ensure safety.”
    • +
+ + +

Passive (avoiding self-reference)

+
    +
  • “A six-month study was conducted to ensure this was the right path.”
    • +
  • “Your personal data is obscured to ensure safety.”
    • +
+ + + +## Use concrete nouns and verbs, not abstractions + +**Why:** abstract language feels like corporate filler. Users want to understand what concrete changes are happening, and their clear implications. + + + +

Don’t

+

“We are moving toward improving user experience.”

+ + +

Do

+

“This update adds spoiler support in comments.”

+ + + +## Name the actor, the action, and the impact + +Every key paragraph should answer: + +- Who is doing it? +- What are we doing? +- Why are we doing it? If we can’t share our reasons, why not? +- How does it affect the reader? + +**Why:** this format creates understanding and can be seen in some of the best-received Meta posts; it avoids the confusion seen in “we are doing this thing” announcements that have been less successful. + + + +

Don’t

+

“We are working on custom badges, which will allow you to have that extra special flair on your profile.”

+ + +

Do

+

“Team X is starting work on a custom badges feature that will allow communities to award users for achievements that are underrepresented or exceptional across the network. You can work with your communities to define what custom badges make sense for each of them.”

+ + + +## Avoid jargon unless technically necessary + +If jargon is required (API, “renderer,” “data dump,” etc.), define it simply (or link to a reliable source where it’s defined) the first time you use it. + +**Why:** even highly technical users appreciate clarity. Ambiguity can result in frustration for the reader. + + + +

Don’t

+

“We’re updating the version of the third-party markdown renderer we use in question & answer pages.”

+ + +

Do

+

“We’re updating the version of the third-party markdown renderer (the software that converts Markdown to HTML) we use in question & answer pages.”

+ + + +## Do not imply certainty when something is still in progress + +If a product or feature is being released in phases, be specific about which phase you’re referring to (alpha, beta, etc.). If a roll-out is planned to take place for different portions of the user base at different times, be specific about the roll-out strategy. Whichever the case, it might be beneficial to define what the release plan is in the context of the particular product, feature, or project you’re communicating about. + +**Why:** when a product or feature is presented as “done” or “released” or “available,” the community assumes that no further work will be done on it to address bug reports, user complaints, or community needs. + + + +

Don’t

+

“This week we’ll be finalizing work on a new-and-improved version of the tag synonyms page, which is planned for release next week.”

+ + +

Do

+

“Starting next week, an alpha version of the tag synonyms page we’ve been working on will be made available for testing for users who’ve signed up for it. The current plan is to follow up with a beta version on DATE, which will be made available to all logged-in users.”

+

“Starting next week, the new version of the tag synonyms page we’ve been working on will be made available to 10% of users. The page will be made available to the rest of the user base in 10% daily increments over the following weeks, assuming we don’t see a significant number of reports about the page’s usage.”

+

“Starting next week, we’ll be rolling out an experiment on the tag synonyms page. For two weeks we’ll monitor performance against the control group (which will be using the current version of the page). We’ll evaluate whether to graduate the feature depending on what we see in the data.”

+ + + +## Be explicit about limitations + +Do not hide the downsides. Avoid using spin (offering a particular interpretation or point of view intended to create a favorable impression) to soften the blow. Avoiding spin can be as simple as choosing the right words, but it’s also good to wholly avoid vague statements that are just aiming to balance out a downside. If what would follow a “but” is a solid statement, let it stand on its own as a separate sentence. If you find yourself writing “It’s possible we will…,” this means it’s just as possible that we won’t do that, and it’s not very reassuring — unless there are immediate plans to explore that thing, don’t use this kind of attempt at reassurance. + +**Why:** open acknowledgement of limitations increases trust. It also avoids users contacting the support channel requesting clarifications about something confusing. + + + +

Don’t

+
    +
  • “This version may not support X, but it’s possible we will explore that in a future update.”
    • +
  • “There might be some accessibility issues with the new rollout.”
    • +
+ + +

Do

+
    +
  • “This version does not support X.”
    • +
  • “Accessibility issues remain, and we are tracking them here.”
    • +
+ + + +## Keep sentences short and scannable + +**Why:** short sentences reduce misinterpretation, especially in high-tension announcements. + + + +

Don’t

+

“Given the importance of Y, by DATE we are planning to roll out an addendum to our Terms of Usage that will accommodate scenario X.”

+ + +

Do

+

“We’re working on an addendum to our Terms of Usage that will accommodate scenario X. This is an important addition because of Y. As per our current timeline, we plan to have the change deployed by DATE.”

+ + + +## Use their language, not ours + +Community members have developed key names by which they refer to parts of our public platform product that may not have a formal name. Those names may differ from our internal informal names (codenames, project nicknames, etc.) for those parts of the product. Always use the terms that community members are familiar with. + +When they exist, make sure you refer to our public products by the names we market them under (“Stack Overflow,” “Stack Exchange,” “Stack Internal,” etc.). If necessary, disambiguate. + +**Why:** + +- Users don’t refer to features or projects by their internal codenames or project names. They’re not familiar with the structure of our product team(s), or which team works on which part of the product, so it’s better to simply refer to the relevant staff by their area of focus, not by non-descriptive team names. +- If we market a public product under a specific name, we should use that name consistently. + + + +

Don’t

+
    +
  • “Bonfire”
    • +
  • “The post has X votes”
    • +
  • “Disco” (or any other team name which you haven’t introduced previously)
    • +
  • “Channels”
    • +
+ + +

Do

+
    +
  • “Chat”
    • +
  • “The post’s score is X”
    • +
  • “The developers”
    • +
  • “Stack Internal (formerly known as Stack Overflow for Teams)”
    • +
+ + diff --git a/packages/stacks-docs/src/docs/public/community/terminology.md b/packages/stacks-docs/src/docs/public/community/terminology.md new file mode 100644 index 0000000000..a93ba86e80 --- /dev/null +++ b/packages/stacks-docs/src/docs/public/community/terminology.md @@ -0,0 +1,78 @@ +--- +title: "Terminology" +description: "Community-specific terminology used across Stack Overflow." +--- + + + + +

For product and brand naming (Stack Overflow, Stack Internal, Stack Ads, etc.), see the public Naming guidelines. This page covers terms specific to community and Meta contexts. Source: Meta Stack Exchange.

+ + +## Stack Exchange + +In 2026 we formalised what had been theoretically [true for over a decade](https://stackoverflow.blog/2015/09/15/were-changing-our-name-back-to-stack-overflow/) by updating our use of language to reflect the fact that the Stack Exchange Network is part of Stack Overflow, rather than Stack Exchange being the parent of Stack Overflow. + +The domain names **stackexchange.com** (and stand-alone urls like **superuser.com**) remain in use, as they carry significant SEO value and are deeply embedded in the communities that use them. Migrating away from these domains would cause unnecessary disruption for no meaningful benefit. + +### Referring to the network of community sites + +"Stack Overflow" now collectively refers to the company and all of its sites. When you need to refer specifically to the broader network of community Q&A sites (formerly "the Stack Exchange network"), use **Stack Overflow Public Platforms**. + +- "The Stack Overflow Public Platforms cover topics from cooking to philosophy" +- "Browse the Stack Overflow Public Platforms at [stackexchange.com/sites](https://stackexchange.com/sites)" + +Avoid using "Stack Exchange" as a standalone term to refer to the company or the network. The name **Stack Exchange** now appears only in two contexts: + +- The legal entity name: **Stack Exchange Inc.** +- Individual site names, which follow the existing **[Topic] Stack Exchange** pattern (e.g. _Physics Stack Exchange_) and have not been rebranded + +Further guidence is [avilable here](/copy/naming#the-website-vs-the-company). + +## Community vs. communities + +Stack Overflow, in its entirety, comprises 180+ sites, and for every one of them there is a corresponding community that formed by bringing that site to life. For that reason, you should generally avoid using the term “community” in its singular form to refer to the whole of users who use the sites. + +You should also avoid using possessive determiners (“_our_ communities”) when referring to the communities or sites, since the company doesn’t own the communities. + +## Network account vs. site profile + +The terms “account” and “profile” are sometimes used interchangeably, but they actually have different meanings. For users to participate on any site, they need to create a profile on that site — which we usually refer to as a “site profile.” If a user chooses to participate on multiple sites, they’ll create a profile for each of the sites they want to participate on. Assuming they use the same email address/credentials for all of these, they will all be tied to the same overarching account — which we usually refer to as a “network account.” + +## Site suspensions, chat suspensions, and post bans (question/answer blocks) + +The term “suspension” or “site suspension” usually refers to suspensions manually applied by site moderators when they determine that a user’s actions are detrimental to the site. During this time “in the penalty box,” the user will not be able to post questions or answers or perform any other action on the site, and their reputation will be locked at 1 until the suspension expires. Any rep they gained over the ban time is gained when the suspension ends, at which point a reputation recount takes place. + +The term “ban” can refer to the automatic question bans and answer bans, automated or manual editing and reviewing bans, which prevent users from doing those activities only (on a specific site). + +The term “ban” or “suspension” can also apply to chat suspensions (which affect all chat rooms under the same domain). + +## Votes vs. post scores vs. user reputation + +Votes are the main way by which users can signal content quality. Clicking the up arrow next to a question or answer registers an upvote, and awards 10 rep to the author. Clicking the down arrow registers a downvote. For most answers, downvoting subtracts 2 rep from the author and 1 rep from the downvoter. For questions there is no penalty for the downvoter. + +Voting affects the post’s score, which is the total number of upvotes minus the total number of downvotes. For example: an answer with 8 upvotes and 3 downvotes has a score of 5. (The number displayed to the left of each post is the net score.) + +Having one’s posts voted on affects their reputation, which is a rough measurement of how much the community trusts that user. Basic use of the site, including asking questions, answering most questions, and suggesting edits, does not require any reputation at all. But the more reputation one earns, the more [privileges](https://meta.stackoverflow.com/privileges) one gains. The primary way to gain reputation is by posting good questions and useful answers. + +## Moderators (usually elected, sometimes appointed) vs. community moderation actions + +A “moderator,” “diamond moderator,” or “mod” for short, is a user that has been elected (or appointed) and has additional powers to oversee a site. They can merge questions, do mass-re-tagging, and have other abilities regular site users don’t. They’re distinguishable by the ♦ after their names on all posts, comments, and chat messages, and on their profile. Some Stack Overflow employees also have the ♦ and moderator powers across [all sites](https://stackexchange.com/sites), along with a “staff” marker. + +The term “moderators” is also sometimes used to refer to users with 10k+ reputation points, who have certain moderation privileges. + +Regular (non-mod) users can perform a variety of actions (such as editing, approving review, closing and reopening posts, etc.) on site despite not having the moderators’ heightened powers, which can also be referred to as “moderation actions” or “curation actions.” + +## Meta — what is it, and how does it work? + +The term “meta” usually refers to the subsite, `sitename.meta.stackexchange.com`, which every site has to handle technical support, feature requests, and discussions about it. [Meta Stack Exchange](https://meta.stackexchange.com) (Meta.SE, MSE) is for questions that apply to the whole network. + +Every site has a help center article that further explains what “meta” is and how it works — [Meta Stack Exchange article](https://meta.stackexchange.com/help/whats-meta) and [stackoverflow.com’s article](https://stackoverflow.com/help/whats-meta). + +The term should be capitalized if referring to a specific meta site, such as using “Meta” in clear reference to Meta Stack Exchange. It should not be capitalized when used in a more generic sense, like a directive to “post on the site’s meta if you have a question.” + +## [status-*] tags and their usage + +Certain tags on Meta, denoted by their red color, can only be added to a question by a moderator or staff member. These tags are reserved for the purpose of giving a feature request or bug an official status from the team. The current relevant tags and their usage were introduced in [this Meta post](https://meta.stackexchange.com/questions/402121/bringing-clarity-to-status-tag-usage-on-meta-sites). diff --git a/packages/stacks-docs/src/docs/public/community/tone.md b/packages/stacks-docs/src/docs/public/community/tone.md new file mode 100644 index 0000000000..651a9067d8 --- /dev/null +++ b/packages/stacks-docs/src/docs/public/community/tone.md @@ -0,0 +1,184 @@ +--- +title: "Tone" +description: "How Stack Overflow’s voice should sound when speaking to Meta audiences." +updated: 2026-04-29 +--- + + + +Stack Overflow’s voice here builds upon the [brand foundations](/copy/voice) — we must sound like a technically competent human speaking clearly and honestly. Our tone should adapt to the situation, but it should never hide information, minimize user concerns, or use “fun engagement” to distract from real issues. Calls-to-action (CTAs) should always be genuine, and never used just to appease the audience — if it’s not important to gather community feedback for some reason (for communications surrounding changes prompted by legal reasons, for instance), don’t explicitly ask the audience for it. + +The individual author’s unique voice, tone, and style can come through, but the topic and nature of the communication should be kept in mind. Conversation starters and requests for substantive feedback may lend themselves to a more casual discourse where that’s helpful, especially if the author’s own perspective is a key element of the communication. However, informative pieces and announcements should generally have a more “just the facts” approach. + +## What our tone should sound like + +### Direct and unambiguous + +- Say what is happening and why. +- Avoid hedging, euphemisms, or corporate phrasing. +- State constraints honestly (technical, legal, or resource limitations). +- Be explicit about how long the post you’re making will be monitored for feedback. + +**Why:** good communication succeeds because transparency builds trust. Users respond better when they understand context, reasoning, and limitations. + + + +

Don’t

+

“We’re improving review queues, and expect to maximize workflow efficiency for users. We’ll keep an eye on impact for some time, in order to minimize disruption.”

+ + +

Do

+

“To pay down some tech debt, we’re making improvements to the back-end architecture for review queues. This may affect user workflows in unpredictable ways, so we’ll be monitoring Meta for related reports in the coming 2 months.”

+ + + +### Human, not “crafted” + +- Use everyday language, not buzzwords. +- Acknowledge how a change might impact the users in plain terms. +- Humor is fine when context allows, but not when announcing changes that are likely to be perceived negatively by the community. +- Be mindful of the fact that we have a global audience when using humor and cultural references or metaphors. + +**Why:** “cute,” “fluffy,” or heavily branded tones may feel disrespectful if readers feel their concerns aren’t being addressed directly and fairly. + + + +

Don’t

+

“In order to bring the future into the platform by integrating AI solutions, we’re moving some cheese around. We expect you’ll see a variety of funky behavior, but we can always blame solar flares for that!”

+ + +

Do

+

“We’re improving our search functionality by integrating AI components into it. We expect this may negatively affect some search results in the short term, but honestly any change to the current search functionality is likely a step up.”

+ + + +### Respectful and collaborative + +- Treat users and moderators as partners, not passive recipients. +- Validate concerns and show awareness of past pain points. +- Respond promptly when users ask clarifying questions. + +**Why:** community members expect staff to not avoid difficult topics, and instead engage on these topics in a way that acknowledges the communities’ role as stakeholders. + + + +

Don’t

+

“We’ve realized how inefficient the question reopening system is after some internal analysis. Our findings show X, Y, and Z. We plan to address those problems by doing A, B, and C.”

+ + +

Do

+

“You’ve told us several times about how inefficient the question reopening system is. We’ve finally devoted some time to fixing it, taking your past input as a key part of our problem definition phase.”

+ + + +### Tone must match the seriousness of the content + +- For feature delays, the tone should be empathetic and factual. +- For policy changes, the tone should be precise and definitive. +- For bug fix announcements, the tone should be technical, transparent, and actionable. + +**Why:** mismatch between tone and situation may trigger frustration and resentment. For example, using a cheerful tone to announce controversial changes may further exacerbate readers’ negative feelings. + +#### Feature delays + + + +

Don’t

+

“Oops! Work on feature Y was delayed due to unforeseen circumstances. We plan to deliver it as soon as possible, though, so you shouldn’t experience too much of a disruption.”

+ + +

Do

+

“Our timeline for delivering feature Y has been delayed for roughly a month, in part due to incident X two weeks ago. We know this causes some inconvenience for a lot of our users, and are making this our top priority in the coming month. Our new deadline to deliver feature Y is DATE.”

+ + + +#### Policy changes + + + +

Don’t

+

“We believe our Privacy Policy needs to change to reflect the new reality we’re facing as a company, in which partnerships like the one with Y become common.”

+ + +

Do

+

“The Privacy Policy will be edited on DATE. This change will take place in order to accommodate some technical aspects of our partnership with Y, explained further down in this post.”

+ + + +#### Bug fix announcements + + + +

Don’t

+

“Thank you for your report. We’ve fixed the bug now.”

+ + +

Do

+

“When we integrated with Z for better spam prevention last month, we failed to account for edge case X. I’ve now gone over the relevant code and did Y, to ensure edge cases like X won’t happen again. If you see the issue persist, please respond to this post.”

+ + + +## What our tone should never sound like + +### Overly polished, vague, or heavy on marketing fluff + + + +

Don’t

+
    +
  • “We believe this change supports our vision of creating the world’s leading knowledge repository for veteran and aspiring technologists.”
    • +
  • “We’re excited to announce…” (when announcing something painful or controversial)
    • +
+ + +

Do

+
    +
  • “This change introduces mechanisms for validating whether content is obsolete and needs to be updated by curators. This is an important piece of ensuring the relevance of content on the platform for future readers.”
    • +
  • “We understand a lot of you may be concerned or frustrated by this change.”
    • +
+ + + +### Minimizing or dodging hard questions + + + +

Don’t

+
    +
  • “Details are in the press release.”
    • +
  • “This work is just starting…” (without clarifying what we do know)
    • +
+ + +

Do

+
    +
  • Quote relevant portions from sources, and explain using different language if relevant.
    • +
  • Clarify up front what things we know, and as many open questions as we might have and anticipate users will ask about.
    • +
+ + + +### One-way broadcast tone + + + +

Don’t

+
    +
  • Make announcements without follow-up.
    • +
  • Post unclear updates with no engagement.
    • +
  • Ignore direct questions.
    • +
+ + +

Do

+
    +
  • Return to the post to monitor and respond to actionable feedback, or requests for clarification.
    • +
  • Respond to questions directly, as much as you can.
    • +
+ + diff --git a/packages/stacks-docs/src/structure.yaml b/packages/stacks-docs/src/structure.yaml index 9ee7439a2d..f1b5a1283a 100644 --- a/packages/stacks-docs/src/structure.yaml +++ b/packages/stacks-docs/src/structure.yaml @@ -61,28 +61,23 @@ navigation: - title: "Community" slug: "community" - description: "How to consider community when working on Stack Overflow." - private: true # private for now while in review + description: "Writing for community when working on Stack Overflow." items: - title: "Audiences" slug: "audiences" image: "/images/heros/audiences.svg" - private: true - title: "Tone" slug: "tone" image: "/images/heros/tone.svg" - private: true - title: "Language & grammar" slug: "language" image: "/images/heros/language_grammar.svg" - private: true - title: "Terminology" slug: "terminology" image: "/images/heros/terminology.svg" - private: true - title: "Product" slug: "system" From 0b7fbb0080653410bed2327c9078e404f0049c47 Mon Sep 17 00:00:00 2001 From: David Longworth Date: Tue, 19 May 2026 17:44:17 +0100 Subject: [PATCH 14/22] reorganize --- .../src/docs/public/community/terminology.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/packages/stacks-docs/src/docs/public/community/terminology.md b/packages/stacks-docs/src/docs/public/community/terminology.md index a93ba86e80..acad907649 100644 --- a/packages/stacks-docs/src/docs/public/community/terminology.md +++ b/packages/stacks-docs/src/docs/public/community/terminology.md @@ -11,6 +11,14 @@ description: "Community-specific terminology used across Stack Overflow."

For product and brand naming (Stack Overflow, Stack Internal, Stack Ads, etc.), see the public Naming guidelines. This page covers terms specific to community and Meta contexts. Source: Meta Stack Exchange.

+## Meta — what is it, and how does it work? + +The term “meta” usually refers to the subsite, `sitename.meta.stackexchange.com`, which every site has to handle technical support, feature requests, and discussions about it. [Meta Stack Exchange](https://meta.stackexchange.com) (Meta.SE, MSE) is for questions that apply to the whole network. + +Every site has a help center article that further explains what “meta” is and how it works — [Meta Stack Exchange article](https://meta.stackexchange.com/help/whats-meta) and [stackoverflow.com’s article](https://stackoverflow.com/help/whats-meta). + +The term should be capitalized if referring to a specific meta site, such as using “Meta” in clear reference to Meta Stack Exchange. It should not be capitalized when used in a more generic sense, like a directive to “post on the site’s meta if you have a question.” + ## Stack Exchange In 2026 we formalised what had been theoretically [true for over a decade](https://stackoverflow.blog/2015/09/15/were-changing-our-name-back-to-stack-overflow/) by updating our use of language to reflect the fact that the Stack Exchange Network is part of Stack Overflow, rather than Stack Exchange being the parent of Stack Overflow. @@ -65,14 +73,6 @@ The term “moderators” is also sometimes used to refer to users with 10k+ rep Regular (non-mod) users can perform a variety of actions (such as editing, approving review, closing and reopening posts, etc.) on site despite not having the moderators’ heightened powers, which can also be referred to as “moderation actions” or “curation actions.” -## Meta — what is it, and how does it work? - -The term “meta” usually refers to the subsite, `sitename.meta.stackexchange.com`, which every site has to handle technical support, feature requests, and discussions about it. [Meta Stack Exchange](https://meta.stackexchange.com) (Meta.SE, MSE) is for questions that apply to the whole network. - -Every site has a help center article that further explains what “meta” is and how it works — [Meta Stack Exchange article](https://meta.stackexchange.com/help/whats-meta) and [stackoverflow.com’s article](https://stackoverflow.com/help/whats-meta). - -The term should be capitalized if referring to a specific meta site, such as using “Meta” in clear reference to Meta Stack Exchange. It should not be capitalized when used in a more generic sense, like a directive to “post on the site’s meta if you have a question.” - ## [status-*] tags and their usage Certain tags on Meta, denoted by their red color, can only be added to a question by a moderator or staff member. These tags are reserved for the purpose of giving a feature request or bug an official status from the team. The current relevant tags and their usage were introduced in [this Meta post](https://meta.stackexchange.com/questions/402121/bringing-clarity-to-status-tag-usage-on-meta-sites). From 578ed7ae569446db51d0723377be09684737256e Mon Sep 17 00:00:00 2001 From: David Longworth Date: Tue, 19 May 2026 17:50:30 +0100 Subject: [PATCH 15/22] link what is meta --- packages/stacks-docs/src/docs/public/community/audiences.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/stacks-docs/src/docs/public/community/audiences.md b/packages/stacks-docs/src/docs/public/community/audiences.md index 4602f42fbb..ff91aa4147 100644 --- a/packages/stacks-docs/src/docs/public/community/audiences.md +++ b/packages/stacks-docs/src/docs/public/community/audiences.md @@ -11,7 +11,7 @@ updated: 2026-04-29 import GridColumn from '$components/GridColumn.svelte'; -Meta sites are the backbone of Stack Overflow’s Public Platforms – a space where the community discusses how the site should work, raises issues, and influences decisions. For sites with their own domain you can find them at `meta.` + the domain, e.g. meta.stackoverflow.com and subdomain sites you can find them at `sitename.meta.`stackexchange.com e.g., math.meta.stackexchange.com +[Meta sites](/community/terminology#meta--what-is-it-and-how-does-it-work) are the backbone of Stack Overflow’s Public Platforms – a space where the community discusses how the site should work, raises issues, and influences decisions. For sites with their own domain you can find them at `meta.` + the domain, e.g. meta.stackoverflow.com and subdomain sites you can find them at `sitename.meta.`stackexchange.com e.g., math.meta.stackexchange.com ## Introduction From de645c9c5504ba5ae01fad961e634a033b2c8488 Mon Sep 17 00:00:00 2001 From: David Longworth Date: Tue, 19 May 2026 17:56:39 +0100 Subject: [PATCH 16/22] add updated timestamp to terminology --- packages/stacks-docs/src/docs/public/community/terminology.md | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/stacks-docs/src/docs/public/community/terminology.md b/packages/stacks-docs/src/docs/public/community/terminology.md index acad907649..71fc57ce30 100644 --- a/packages/stacks-docs/src/docs/public/community/terminology.md +++ b/packages/stacks-docs/src/docs/public/community/terminology.md @@ -1,6 +1,7 @@ --- title: "Terminology" description: "Community-specific terminology used across Stack Overflow." +updated: 2026-05-19 --- -[Meta sites](/community/terminology#meta--what-is-it-and-how-does-it-work) are the backbone of Stack Overflow’s Public Platforms – a space where the community discusses how the site should work, raises issues, and influences decisions. For sites with their own domain you can find them at `meta.` + the domain, e.g. meta.stackoverflow.com and subdomain sites you can find them at `sitename.meta.`stackexchange.com e.g., math.meta.stackexchange.com +[Meta sites](/community/terminology#meta--what-is-it-and-how-does-it-work) are the backbone of Stack Overflow’s Public Platforms — a space where the community discusses how the site should work, raises issues, and influences decisions. For sites with their own domain, you can find them at `meta.` + the domain (e.g., `meta.stackoverflow.com`). For subdomain sites, you can find them at `sitename.meta.stackexchange.com` (e.g., `math.meta.stackexchange.com`). ## Introduction @@ -23,7 +23,7 @@ For the purposes of these guidelines, we’re roughly dividing the people you mi **Seasoned users** are perhaps slow to trust or get excited about something that is new, or a shift from “the way things have always been.” Every good public communication is an opportunity to earn their confidence and build trust, and every bad public communication risks confirming their suspicions and fueling skepticism. The goal isn’t just to inform, but to convey that the company understands their craft, respects their investment of time on the platform, and values their opinions. Empathy is key: recognize the disruption that platform changes may cause for seasoned users. When speaking to seasoned users, write as a peer seeking collaboration. Use language that minimizes the emotional distance between you and the reader. **Calls-to-action are for collaboration and feedback.** -This group includes the traditional, somewhat loosely-defined roles we often refer to in product development: active/engaged user, contributor, curator, leader, moderator. When crafting communication focused on actions some of these groups perform (or that we hope they perform), it’s important to understand the role being targeted. But note that there is much overlap in those roles, and an individual user’s actions may fit into multiple roles. +This group includes the traditional, somewhat loosely defined roles we often refer to in product development: active/engaged user, contributor, curator, leader, moderator. When crafting communication focused on actions some of these groups perform (or that we hope they perform), it’s important to understand the role being targeted. But note that there is much overlap in those roles, and an individual user’s actions may fit into multiple roles. diff --git a/packages/stacks-docs/src/docs/public/community/language.md b/packages/stacks-docs/src/docs/public/community/language.md index 8a581969c9..b7c0f9a6fa 100644 --- a/packages/stacks-docs/src/docs/public/community/language.md +++ b/packages/stacks-docs/src/docs/public/community/language.md @@ -19,7 +19,7 @@ Language and grammar aren’t just mechanical decisions: they should structure c ## Prefer active voice over passive voice -**Why:** passive voice hides responsibility and feels evasive, and is strongly associated with “bad communication” examples. +**Why:** passive voice hides responsibility, feels evasive, and is strongly associated with “bad communication” examples. - While it’s generally best to avoid the passive voice, in certain situations it helps you sound softer without adding too many words. - You can also occasionally use the passive voice to avoid excessively referring to yourself or Stack Overflow — as long as you’ve primarily used active voice (to make it clear we’re taking ownership of our actions). diff --git a/packages/stacks-docs/src/docs/public/community/terminology.md b/packages/stacks-docs/src/docs/public/community/terminology.md index 8753462eef..e1bbff0983 100644 --- a/packages/stacks-docs/src/docs/public/community/terminology.md +++ b/packages/stacks-docs/src/docs/public/community/terminology.md @@ -22,9 +22,9 @@ The term should be capitalized if referring to a specific meta site, such as usi ## Stack Exchange -In 2026 we formalised what had been theoretically [true for over a decade](https://stackoverflow.blog/2015/09/15/were-changing-our-name-back-to-stack-overflow/) by updating our use of language to reflect the fact that the Stack Exchange Network is part of Stack Overflow, rather than Stack Exchange being the parent of Stack Overflow. +In 2026 we formalized what had been theoretically [true for over a decade](https://stackoverflow.blog/2015/09/15/were-changing-our-name-back-to-stack-overflow/) by updating our use of language to reflect the fact that the Stack Exchange Network is part of Stack Overflow, rather than Stack Exchange being the parent of Stack Overflow. -The domain names **stackexchange.com** (and stand-alone urls like **superuser.com**) remain in use, as they carry significant SEO value and are deeply embedded in the communities that use them. Migrating away from these domains would cause unnecessary disruption for no meaningful benefit. +The domain names **stackexchange.com** (and stand-alone URLs like **superuser.com**) remain in use, as they carry significant SEO value and are deeply embedded in the communities that use them. Migrating away from these domains would cause unnecessary disruption for no meaningful benefit. ### Referring to the network of community sites @@ -38,7 +38,7 @@ Avoid using "Stack Exchange" as a standalone term to refer to the company or the - The legal entity name: **Stack Exchange Inc.** - Individual site names, which follow the existing **[Topic] Stack Exchange** pattern (e.g. _Physics Stack Exchange_) and have not been rebranded. -Further guidence is [available here](/copy/naming#the-website-vs-the-company). +Further guidance is [available here](/copy/naming#the-website-vs-the-company). ## Community vs. communities diff --git a/packages/stacks-docs/src/docs/public/community/tone.md b/packages/stacks-docs/src/docs/public/community/tone.md index 651a9067d8..f29bb55dcb 100644 --- a/packages/stacks-docs/src/docs/public/community/tone.md +++ b/packages/stacks-docs/src/docs/public/community/tone.md @@ -119,7 +119,7 @@ The individual author’s unique voice, tone, and style can come through, but th

Do

-

“When we integrated with Z for better spam prevention last month, we failed to account for edge case X. I’ve now gone over the relevant code and did Y, to ensure edge cases like X won’t happen again. If you see the issue persist, please respond to this post.”

+

“When we integrated with Z for better spam prevention last month, we failed to account for edge case X. I’ve now gone over the relevant code and done Y, to ensure edge cases like X won’t happen again. If you see the issue persist, please respond to this post.”

 From 7c9b1c2d2dd921b97af9e714d71ea1911f3cdabe Mon Sep 17 00:00:00 2001 From: David Longworth Date: Wed, 20 May 2026 12:36:40 +0100 Subject: [PATCH 19/22] a few more --- packages/stacks-docs/src/docs/public/community/language.md | 6 +++--- packages/stacks-docs/src/docs/public/community/tone.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/stacks-docs/src/docs/public/community/language.md b/packages/stacks-docs/src/docs/public/community/language.md index b7c0f9a6fa..9db461b4d7 100644 --- a/packages/stacks-docs/src/docs/public/community/language.md +++ b/packages/stacks-docs/src/docs/public/community/language.md @@ -11,7 +11,7 @@ updated: 2026-04-29 import GridColumn from '$components/GridColumn.svelte'; -Language and grammar aren’t just mechanical decisions: they should structure clarity, remove ambiguity, and make messages readable for both novice and experienced users. Our grammatical guidelines should reduce confusion and improve consistency in communication from across teams. +Language and grammar aren’t just mechanical decisions: they should create clarity, remove ambiguity, and make messages readable for both novice and experienced users. Our grammatical guidelines should reduce confusion and improve consistency in communication from across teams.

The public Style guide covers brand-wide grammar and mechanics. The guidance below is specific to Meta posts.

@@ -130,7 +130,7 @@ If jargon is required (API, “renderer,” “data dump,” etc.), define it si ## Do not imply certainty when something is still in progress -If a product or feature is being released in phases, be specific about which phase you’re referring to (alpha, beta, etc.). If a roll-out is planned to take place for different portions of the user base at different times, be specific about the roll-out strategy. Whichever the case, it might be beneficial to define what the release plan is in the context of the particular product, feature, or project you’re communicating about. +If a product or feature is being released in phases, be specific about which phase you’re referring to (alpha, beta, etc.). If a rollout is planned to take place for different portions of the user base at different times, be specific about the rollout strategy. Whichever the case, it might be beneficial to define what the release plan is in the context of the particular product, feature, or project you’re communicating about. **Why:** when a product or feature is presented as “done” or “released” or “available,” the community assumes that no further work will be done on it to address bug reports, user complaints, or community needs. @@ -151,7 +151,7 @@ If a product or feature is being released in phases, be specific about which pha Do not hide the downsides. Avoid using spin (offering a particular interpretation or point of view intended to create a favorable impression) to soften the blow. Avoiding spin can be as simple as choosing the right words, but it’s also good to wholly avoid vague statements that are just aiming to balance out a downside. If what would follow a “but” is a solid statement, let it stand on its own as a separate sentence. If you find yourself writing “It’s possible we will…,” this means it’s just as possible that we won’t do that, and it’s not very reassuring — unless there are immediate plans to explore that thing, don’t use this kind of attempt at reassurance. -**Why:** open acknowledgement of limitations increases trust. It also avoids users contacting the support channel requesting clarifications about something confusing. +**Why:** open acknowledgment of limitations increases trust. It also avoids users contacting the support channel requesting clarifications about something confusing. diff --git a/packages/stacks-docs/src/docs/public/community/tone.md b/packages/stacks-docs/src/docs/public/community/tone.md index f29bb55dcb..7697284d4a 100644 --- a/packages/stacks-docs/src/docs/public/community/tone.md +++ b/packages/stacks-docs/src/docs/public/community/tone.md @@ -63,7 +63,7 @@ The individual author’s unique voice, tone, and style can come through, but th - Validate concerns and show awareness of past pain points. - Respond promptly when users ask clarifying questions. -**Why:** community members expect staff to not avoid difficult topics, and instead engage on these topics in a way that acknowledges the communities’ role as stakeholders. +**Why:** community members expect staff to engage with difficult topics rather than avoid them, in a way that acknowledges the communities’ role as stakeholders. From 22e5b0bac27f8251af4265bbcace824303aeaad5 Mon Sep 17 00:00:00 2001 From: David Longworth Date: Wed, 20 May 2026 13:01:29 +0100 Subject: [PATCH 20/22] consolidate guidence --- .../src/docs/public/community/terminology.md | 22 ++--- .../src/docs/public/copy/naming.md | 86 +++++++++++++++++-- 2 files changed, 84 insertions(+), 24 deletions(-) diff --git a/packages/stacks-docs/src/docs/public/community/terminology.md b/packages/stacks-docs/src/docs/public/community/terminology.md index e1bbff0983..164f6d8f38 100644 --- a/packages/stacks-docs/src/docs/public/community/terminology.md +++ b/packages/stacks-docs/src/docs/public/community/terminology.md @@ -22,23 +22,13 @@ The term should be capitalized if referring to a specific meta site, such as usi ## Stack Exchange -In 2026 we formalized what had been theoretically [true for over a decade](https://stackoverflow.blog/2015/09/15/were-changing-our-name-back-to-stack-overflow/) by updating our use of language to reflect the fact that the Stack Exchange Network is part of Stack Overflow, rather than Stack Exchange being the parent of Stack Overflow. +In 2026 we formalized what had been theoretically [true for over a decade](https://stackoverflow.blog/2015/09/15/wer-e-changing-our-name-back-to-stack-overflow/) by updating our use of language to reflect the fact that the Stack Exchange Network is part of Stack Overflow, rather than Stack Exchange being the parent of Stack Overflow. + +For naming usage, see the Naming guide: -The domain names **stackexchange.com** (and stand-alone URLs like **superuser.com**) remain in use, as they carry significant SEO value and are deeply embedded in the communities that use them. Migrating away from these domains would cause unnecessary disruption for no meaningful benefit. - -### Referring to the network of community sites - -"Stack Overflow" now collectively refers to the company and all of its sites. When you need to refer specifically to the broader network of community Q&A sites (formerly "the Stack Exchange network"), use **Stack Overflow Public Platforms**. - -- "The Stack Overflow Public Platforms cover topics from cooking to philosophy" -- "Browse the Stack Overflow Public Platforms at [stackexchange.com/sites](https://stackexchange.com/sites)" - -Avoid using "Stack Exchange" as a standalone term to refer to the company or the network. The name **Stack Exchange** now appears only in two contexts: - -- The legal entity name: **Stack Exchange Inc.** -- Individual site names, which follow the existing **[Topic] Stack Exchange** pattern (e.g. _Physics Stack Exchange_) and have not been rebranded. - -Further guidance is [available here](/copy/naming#the-website-vs-the-company). +- [The flagship site vs the network](/copy/naming#the-flagship-site-vs-the-network): Stack Overflow vs Stack Overflow Public Platforms +- [Shorthand for individual sites](/copy/naming#shorthand-for-individual-sites): “a site,” “the site,” “sites” +- [Where “Stack Exchange” still applies](/copy/naming#where-stack-exchange-still-applies): legal entity, site name pattern, domains ## Community vs. communities diff --git a/packages/stacks-docs/src/docs/public/copy/naming.md b/packages/stacks-docs/src/docs/public/copy/naming.md index 9873c287ae..cb4b284c64 100644 --- a/packages/stacks-docs/src/docs/public/copy/naming.md +++ b/packages/stacks-docs/src/docs/public/copy/naming.md @@ -1,5 +1,5 @@ --- -updated: 2025-12-11 +updated: 2026-05-20 ---