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..072031dd42 --- /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](/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 + +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..9db461b4d7 --- /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 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.

+
+ +## Prefer active voice over passive voice + +**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). +- 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)

+ +
+ +

Passive (softened when needed)

+ +
+
+ + + +

Active (strong first person)

+ +
+ +

Passive (avoiding self-reference)

+ +
+
+ +## 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 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. + + + +

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 acknowledgment of limitations increases trust. It also avoids users contacting the support channel requesting clarifications about something confusing. + + + +

Don’t

+ +
+ +

Do

+ +
+
+ +## 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

+ +
+ +

Do

+ +
+
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..a0e1ef7fa0 --- /dev/null +++ b/packages/stacks-docs/src/docs/public/community/terminology.md @@ -0,0 +1,69 @@ +--- +title: "Terminology" +description: "Community-specific terminology used across Stack Overflow." +updated: 2026-05-19 +--- + + + + +

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 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. + +For naming usage, see the Naming guide: + +- [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 + +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.” + +## [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..7697284d4a --- /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 engage with difficult topics rather than avoid them, 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 done 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

+ +
+ +

Do

+ +
+
+ +### Minimizing or dodging hard questions + + + +

Don’t

+ +
+ +

Do

+ +
+
+ +### One-way broadcast tone + + + +

Don’t

+ +
+ +

Do

+ +
+
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 --- @@ -38,8 +49,8 @@ -
-
+
+ diff --git a/packages/stacks-docs/src/structure.yaml b/packages/stacks-docs/src/structure.yaml index 3dd553d43b..6587691859 100644 --- a/packages/stacks-docs/src/structure.yaml +++ b/packages/stacks-docs/src/structure.yaml @@ -59,6 +59,26 @@ navigation: - title: "Settings & preferences" slug: "settings" + - title: "Community" + slug: "community" + description: "Writing for community when working on Stack Overflow." + items: + - title: "Audiences" + slug: "audiences" + image: "/images/heros/audiences.svg" + + - title: "Tone" + slug: "tone" + image: "/images/heros/tone.svg" + + - title: "Language & grammar" + slug: "language" + image: "/images/heros/language_grammar.svg" + + - title: "Terminology" + slug: "terminology" + image: "/images/heros/terminology.svg" + - title: "Product" slug: "system" description: "Components & guidelines for devleopers when building Stack Overflow." 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