Voice and tone
The difference between voice and tone, and how each applies to Stack Overflow.
Voice is the company’s public personality. A clear, consistent voice makes all communications sound like they came from the same place.
- Be upfront with users, especially if we make a mistake.
- Back up claims with facts and concrete examples.
- Break down complicated situations into steps to help users focus on one thing at at time.
- Communicate in a way that’s thoughtful toward people’s situations and emotions.
- Offer encouragement and practical advice.
- Help people on their own terms by using words they’ll understand.
- Don’t talk down to users.
- Don’t assume users are familiar with Stack Overflow or how it works.
- Help people succeed by speaking plainly at the moments they’re likely to need help.
- Be straightforward about our mission to be a welcoming, inclusive community.
- Avoid us vs. them binaries (eg. newbies vs. power users)
| Don’t | Do |
|---|---|
| “Join us in building an expert community of the best developers in the world.” | “Join us in building a community where all people feel welcome and can participate, regardless of expertise or identity.” |
| “Join us in a movement to diversify the developer community and amplify marginalized voices in technology.” | |
| “If you’re new to the site, make it as easy as possible for experienced community members to help you. Remember that they are volunteers.” | “If you’re here to get help, make it as easy as possible for others to help you. Follow our guidelines and remember that our community is made possible by volunteers.” |
| “If you’re an experienced contributor, be patient and welcoming. New users may have a hard time learning how to participate in our community.” | “If you’re here to help others, be patient and welcoming. Learning how to participate in our community can be hard. Offer support if you see someone struggling or otherwise in need of help.” |
Tone changes to fit the situation. Help people succeed by showing your empathy and matching your tone with the user’s emotions and situations, especially in times of stress or confusion. Avoid jargon unless it’s absolutely necessary. Let people know how things will benefit them, and what they can do next.
In positive situations, a user may feel interest, curiosity, and/or delight. You can match those emotions by adopting an encouraging and friendly tone. If you’re writing good news like an announcement or confirmation, it’s ok to be more casual.
| Context | Don’t | Do |
|---|---|---|
| Payment successfully processed | “We have processed your payment for 65 Candidate Search seats on June 12, 2018. View receipt” | “Your payment has been successfully processed. View receipt” |
| Team has hit 100 answer milestone | “Your team contributed 100 answers, 90 questions, 354 upvotes, and 19 edits in the last 30 days.” | “Your team contributed 100 answers last month! Continue growing your team’s knowledge by inviting more team members.” |
In neutral situations, the user may feel interest, curiosity, and/or stress. You can match these emotions by adopting a straightforward and helpful tone. If you’re providing instructions, provide enough detail to give the user confidence. Avoid telling the user how they should think or feel.
| Context | Don’t | Do |
|---|---|---|
| User’s bounty has been posted | “Your bounty has been posted. The bountied question will get a special indicator and appear on the Featured tab for one week. Don’t worry if you don’t get the answer you want – you can always post another bounty.” | “Your bounty has been posted. You’ll be notified when you receive answers.” |
| First time posting an answer | “Tags come with advanced features like tag watching, wikis, and synonyms.” | “Use tags to add as much (or as little) structure as your organization needs.” |
In negative situations, the user might be feeling confusion, stress, annoyance, and even anger. Match their emotions by adopting a gentle, calm, and serious tone. These are important moments to show readers that you care about their feelings. Write calmly so people can focus on your message. Avoid scary, technical terms and words like “alert,” “immediately,” or “urgent” unless they’re absolutely necessary. Let people know what went wrong, and tell them what they should do next
| Context | Don’t | Do |
|---|---|---|
| No Candidate Search results | “0 results.” | “No candidates matched your search. Try different keywords or adjust your filters.” |
| Account is suspended | “Due to clear signs of falsified accounts being used to artificially inflate your reputation, your account has been temporarily suspended for 7 days. It is not fair to other users of Stack Overflow to allow users to gain reputation through sockpuppets.” |
“We noticed fraudulent voting activity on this account. This violates our community rules, and the account will be suspended for 7 days. If you believe this message is a mistake, let us know.” |
| Error message | “It looks like there are incomplete place-holders; please ensure all necessary detail is complete.” | “Update the placeholder text to continue.” |
This content was adapted from Nicely Said and the Shopify Content Guide.