Grammar and mechanics
A guide to help anyone who writes, edits, or translates public-facing text for Stack Overflow.
You should almost always write in the active voice, particularly if the user needs to do something.
Don’t | Do |
---|---|
“You should update your profile” | “Update your profile” |
While it’s generally best to avoid the passive voice, in certain situations it helps you sound softer without adding too many words. It’s especially useful for time-sensitive messages like payment confirmations and error messages. You can also use the passive voice to avoid referring to yourself or Stack Overflow.
Don’t | Do |
---|---|
“We cancelled your order.” | “Your order has been cancelled.” |
“We’ve suspended your account.” | “Your account has been suspended.” |
Contractions make copy sound more human. Avoid contractions that sound awkward when you say them out loud, or are not commonly used in everyday conversation.
Don’t | Do |
---|---|
“This’ll help you get answers to your questions.” | “It’s designed to help you get answers to your questions.” |
“There must’ve been an error with your order.” | “There’s an error with your order.” |
Use sentence casing for all headings and calls-to-action. Proper or trademarked nouns (e.g. countries, product names) should be capitalized. If a feature or product is unique to Stack Overflow, capitalize it (Stack Overflow for Teams, Stack Overflow Jobs).
Don’t | Do |
---|---|
Performance Overview | Performance overview |
Edit Your Profile | Edit your profile |
Don’t | Do |
---|---|
Post Job | Post job |
flag comment | Flag comment |
cancel | Cancel |
Don’t | Do |
---|---|
Job Alerts | job alerts |
Blog | blog |
Profile | profile |
Stack Overflow talent | Stack Overflow Talent |
stack exchange | Stack Exchange |
Use American spelling for all public-facing content. When in doubt, check the Merriam-Webster dictionary for the preferred spelling of specific terms.
Don’t | Do |
---|---|
Recognise | Recognize |
Travelled | Traveled |
Colour | Color |
9 April 2019 | April 9, 2019 |
Let’s use the abbreviated version of “OK”. This is preferred to “Okay” and its variants. “OK” should be fully capitalized in every context. Tonally, it may be appropriate to use “OK” in an actionable button—if it isn’t used alone.
Don’t | Do |
---|---|
Okay | OK |
okay | |
Ok |
Refer to users as “you.” Don’t put words in their mouths with phrases that use “I” or “my.”
Don’t | Do |
---|---|
Change my email settings | Change your email settings |
When getting consent or granting permissions, refer to users as “I.” In some cases (such as getting someone to grant permissions), refer to users as “I.”
Don’t | Do |
---|---|
You agree to the terms of service | I agree to the terms of service |
When referring to Stack Overflow, use “we.” However, try to avoid inserting Stack Overflow into the content as much as possible.
Don’t | Do |
---|---|
Stack Overflow is here to help. They’ll make changes soon. | Stack Overflow is here to help. We’ll make changes soon. |
Use “their” as a singular, gender-neutral pronoun when the gender of the subject is unknown or unimportant. Avoid using gendered terms.
Don’t | Do |
---|---|
When a new user is added, he or she will be able to edit content. | When a new user is added, they’ll be able to edit content. |
We appreciate the guys and gals of Stack Overflow. | We appreciate the Stack Overflow community. |
Take extra care when using “login,” and “log in.” The former is a noun while the latter is a verb. Do not use “login” as a verb. The same logic applies to “signup,” “sign up.”
Don’t | Do |
---|---|
Login to ask a question | Log in to ask a question |
Add a log in to your account | Add a login to your account |
Signup to ask a question | Sign up to ask a question |
Complete email sign up | Complete email signup |
Don’t use ampersands (&) unless it’s part of a branded term. Spell out the word “and” instead.
Don’t | Do |
---|---|
Update your email address & password | Update your email address and password |
Stack Overflow Q and A | Stack Overflow Q&A |
Use apostrophes to represent omitted letters or numbers (can’t, you’re, ’90s) and to form possessives.
Don’t | Do |
---|---|
Admins role | Admin’s role |
Moderators’s tasks | Moderators’ tasks |
Avoid using colons unless you’re introducing a list. If you need to use a colon in a sentence, don’t capitalize the first word after it.
Don’t | Do |
---|---|
Your job listing was published: On January 15 | Your job listing was published on January 15 |
The ellipses (…) can be used in place of a missing piece of text (most commonly to show the deletion of words from a quote). Avoid using ellipses in text. It’s appropriate to use an ellipses in input placeholder copy. Use the real single character ellipsis unicode (…) instead of three periods (...).
Don’t | Do |
---|---|
Avoid subjective questions… stick to fact-based questions. | Avoid subjective questions. Stick to fact-based questions. |
Search... | Search… |
Don’t use exclamation points unless something is really exciting! If you have to use one, limit yourself to one exclamation mark per page.
Don’t | Do |
---|---|
Your email settings have been saved! | You’ve published your first job listing! |
Use hyphens to combine two words that modify or describe the noun that follows, or join prefixes and suffixes when there are two vowels beside each other.
Use an en dash with no spaces in between (–) for a fixed range of numbers. Avoid using them in a sentence. Avoid using em dashes in microcopy.
Don’t | Do |
---|---|
Start your free 14 day trial. | Start your free 14-day trial. |
January 7 – 9 | January 7–9 |
Get started – sign up today. | Get started. Sign up today. |
Avoid using question marks wherever possible. Reword into affirmative statements wherever you can. It’s okay to use question marks if you don’t know the result of the question (“Did you forget your email?”).
Don’t | Do |
---|---|
Want to learn more? | Learn more |
Use quotation marks to define words (“Accepted answer”) or to quote text. Always use smart, curly quotes (“), not vertical, straight quotes ("). Single curly quotes (’) can be used when nested within a set of double quotes. Place punctuation marks inside quotation marks.
Don’t | Do |
---|---|
“I meet people who use Stack Overflow every single day”, said Joel Spolsky. | “I meet people who use Stack Overflow every single day,” said Joel Spolsky. |
Use the oxford comma in sentences. Don’t use a comma to separate two distinct phrases (comma splicing). Use two sentences instead.
Don’t | Do |
---|---|
Our community is rooted in kindness, collaboration and mutual respect. | Our community is rooted in kindness, collaboration, and mutual respect. |
Thanks for contacting us, we’ll be in touch soon. | Thank you for contacting us. We’ll be in touch soon. |
Don’t use periods in interface copy unless it’s a full sentence or description.
Don’t use periods in: | Do use periods in: |
---|---|
Sentence fragments | Complete sentences |
Top-level headings and titles | Body text, descriptions, and subtitles |
Buttons | Help text under text boxes (form fields) |
Avoid using semicolons. When connecting two closely related ideas, use a comma or write two sentences.
Don’t | Do |
---|---|
We shaved off about five minutes from last year’s survey; the survey should take about 25 minutes to complete. | We shaved off about five minutes from last year’s survey. The survey should take about 25 minutes to complete. |
Buttons and links should be clear and predictable. People should be able to anticipate what will happen when they click or tap. Button and link text should be sentence case and action led (starting with a verb). To provide enough context, use a verb+noun format except for common actions like Save or Close.
Don’t | Do |
---|---|
New team | Create new team |
Settings | View settings |
All headings or subheadings should be concise, scannable, and sentence case. Don’t use periods at the end of headings. If a subheading is a full sentence, you may use a period.
Don’t | Do |
---|---|
Edit Your Profile. | Edit profile |
When writing lists:
- Use a colon (:) to introduce an unordered list.
- Use sentence case.
- If any list item contains two or more sentences, punctuate all list items.
- If all list items are one sentence or fragments, don’t punctuate.
Don’t | Do |
---|---|
To edit your Team’s tags…
|
To edit your Team’s tags:
|