Following grammar, punctuation, and style guidelines helps keep our presentation consistent. Users have a better experience if they know what to expect and where to find the information they need.
Basics
↑ Back to top- Be democratic. Some people read every word; some scan and search or prefer video. Help everyone.
- Be focused. Lead with the most important information first in sentences, paragraphs, and sections.
- Be concise. Use plain language and brief sentences.
- Be consistent. Follow the guidelines and style tips below.
- Be specific. Communicate clearly using fewer, simpler words whenever possible.
Guidelines
↑ Back to topSpelling and grammar
↑ Back to topWe use Merriam-Webster‘s American spelling for all user-facing communications.
Always check your spelling and grammar before publishing. Built-in spell-check tools are common in programs such as Google Docs and Microsoft Word. Free online resources include:
Woo vs WooCommerce
↑ Back to top“Woo” is the name of our company and brand. “WooCommerce” is the name of our beloved and popular ecommerce plugin for WordPress (AKA our core product).
When referring to the company or something the brand does, “Woo” should be used. But when referring to the platform — anything specifically done with or on the platform — it should be “WooCommerce.”
Note: We do sometimes use “Woo” as shorthand for “WooCommerce” in external communications. This should be done sparingly, so as not to cause confusion between the brand and the platform.
Abbreviations and acronyms
↑ Back to topWrite out the full version on the first mention, with the abbreviation or acronym in parentheses. Use the short version for further mentions.
- First use: Payment Card Industry Data Security Standard (PCI-DSS)
- Second use: PCI-DSS
If the abbreviation or acronym is widely known, use it as is.
- API
- FAQ
- HTML
- PHP
- SQL
- SSL
Active voice
↑ Back to topWith active voice, the subject performs an action. With passive voice, the subject has an action done to it.
- Active: Latoya downloaded her extension files.
- Passive: The extension files were downloaded by Latoya.
Capitalization
↑ Back to topWhen we capitalize:
- Blog post and documentation article titles: First word.
- Documentation headings (h2): First word.
- Product names: Every word except prepositions and conjunctions.
- Sentences: First word.
- Unordered/bulleted lists: First word of each entry.
When we use lowercase:
- The word “ecommerce” (not “eCommerce”)
- An email address (michael@thebluthcompany.com)
- A website URL (leftorium.com)
Contractions
↑ Back to topUse with discretion. Contractions — such as “I’m” and “there’s” — give writing an informal and conversational feel, but may be inappropriate if content is translated. For example, the “not” in “don’t” is sometimes ignored by online translators.
Emoji
↑ Back to topUse emoji rarely and intentionally. Do not use emoji on Marketplace product pages or in documentation.
Numbers
↑ Back to topSpell out a number at the start of a sentence, and spell out numbers one through nine in all cases (except on social media or in email subject lines). Use numerals in all other cases.
- Yes: Ten products will launch in June. No: 10 products will launch in June.
- Marta ran a marathon and won third place in her age group.
- Shani bought five hammers and 21 types of nails for the building project.
- There were four kinds of kombucha on tap.
Use a comma for numbers with more than three digits:
- 41,500
- 170,000
- 1,000,000 (or 1 million)
Currency
Use currency codes and not just a symbol/sign when specifying dollars. Whole amounts need not have a decimal and two places.
- $20 USD
- $19.99 CAD
- $39.50 AUD
When writing about other currencies, use the appropriate symbol/sign.
- €995
- ¥5,000
- £18.99
Dates
Spell out the day of the week and month, using the following format:
- Monday, January 29, 2024
Decimals
Use decimal points when a number is difficult to convert to a fraction, such as:
- 3.141
- 98.5
- 0.29
Fractions
Spell out fractions, such as one-third.
Percentages
Spell out the word “percent”. Don’t use the % symbol unless space is limited, e.g. on social media or email subject lines.
Phone numbers
Use hyphens without spaces between numbers, not parentheses or periods. Include a country code prefix for all countries.
- +1-555-867-5309
- +34-902-1899-00
Range and span
Use an en dash (–) to indicate a range or span of numbers, such as 20–30 days. See Dashes and hyphens.
Temperature
Use the degree symbol with a capital C abbreviation for Celsius or a capital F abbreviation for Fahrenheit. Do not add a space between the symbol and the abbreviation.
- 27°C
- 98°F
Times
Use numbers 0–12 with lowercase am or pm, including a space. Do not include a period unless at the end of a sentence.
- 7:00 am
- 4:30 pm
Use an en dash (–) between times to indicate a period in am or pm. Use the word to if the period spans am and pm. See Dashes and hyphens.
- 7:00–9:00 am
- 9:15 am to 10:30 pm
Specify a time zone when writing about an event. We use Coordinated Universal Time (UTC).
Abbreviate US time zones:
- Eastern Time: EDT, EST, or ET.
- Central Time: CDT, CST, or CT.
- Mountain Time: MDT, MST, or MT.
- Pacific Time: PDT, PST, or PT.
When multiple times are displayed, show the latest first:
- 5 pm UTC/9 am ET/6 am PT
Years
Abbreviate decades; do not use apostrophes.
- 80s and 90s
- 1900s and 1890s
Punctuation
↑ Back to topAmpersands
Ampersands need only be used when part of an official company/brand name. Please do not substitute it for “and”.
- Yes: Ben & Jerry’s
- No: Andrei, Tiago, and Yida went to a football game at Camp Nou.
Apostrophes
An apostrophe makes a word possessive. If a word already ends in “s” and is singular, add an apostrophe before the “s”. If the word ends in “s” and is plural, add an apostrophe after the “s”.
- A friend borrowed Fernando’s bike.
- Laura hid the office managers’ pens.
These are possessives:
- The FAQ’s questions
- An HE’s weekly rotation
These are plural:
- FAQs
- HEs
Colons
Use a colon to create a short list:
- Erika ordered three kinds of donuts: glazed, chocolate, and sprinkle dip.
Semicolons
Semicolons can be used to join two related phrases:
- Their debut solo album hit the Top 10 in 20 countries; it was #1 in Spain.
Commas
Use a serial comma — also known as an Oxford comma — when compiling a list:
- Mahrie likes sunflowers, daisies, and peonies.
Use common sense for other cases. Read the sentence out loud, and use a comma where clarity or a pause may be needed.
Periods/full stops
Always use a period/full stop at the end of a sentence. If a full sentence is listed within a bullet point, it should end with a period.
For example:
- When you are learning a new language, it is essential to know the grammar.
If, on the other hand, you’re listing words or short phrases, you should omit the period. For example:
Don’t forget to bring the following:
- Laptop
- English dictionary and thesaurus
- Vanessa’s old recipe book
When listing a longer sentence fragment or incomplete sentence, include a period. For example:
Useful language learning techniques include:
- Visiting the country where the language is spoken.
- Practicing the language with a native speaker.
- Reading books in the language.
For full sentences combined with fragments, include a period at the end of each item in a mixed list. For example:
My thoughts on English grammar:
- It’s complicated and potentially confusing.
- Useful to know, especially in an increasingly globalized market.
- Great fun, nonetheless.
For more on period use, see Quotation Marks.
Dashes and hyphens
Use a hyphen (-) without spaces on either side to form compound words:
- first-time user
- over-the-counter
Use an en dash (–) to indicate a span or range:
- The information is in chapters 8–10 of Jonathan’s report.
- The 2023–2024 season was the best yet for our company pétanque team.
Use an em dash (—) with a space on either side to indicate an aside or emphasis. Use a true em dash, not a hyphen or en dash.
- Multivariate testing — one of our new Pro features — can help you grow your business.
- Olivia thought Wally was the sandwich thief, but she was wrong — it was a deer.
When adding a line break to a sentence containing an em dash, keep the em dash on the preceding line:
Reach more customers in 2024 with RachelPay —
get up to 50% off fees for 30 days.
This is commonly used for placements when space for copy is limited, e.g. a site banner.
See How to type em dash and en dash symbols on a PC or Mac keyboard.
Ellipses
Ellipses can be used to indicate an indefinite ending to a sentence or to show words are omitted when used in brackets […]. Use sparingly.
Exclamations
Use an exclamation mark/point rarely and use only one at a time. Exclamations follow the same placement convention explained in Periods. Periods and exclamations should be:
- inside quotation marks.
- outside parentheses when the portion in parentheses is part of a larger sentence.
- inside parentheses when the part in parentheses can stand on its own.
Examples:
- Brent said, “I had the best day ever!”
- Olivia went to the supermarket (and to the nail salon).
- Jay loves pizza and cream soda! (Cream soda needs to be cold.)
Question marks
Question marks follow the same placement convention explained in Periods.
Quotation marks
Periods and commas are placed within quotation marks. Question marks within quotes follow logic — if the question mark is part of the quotation, it goes within. If you’re asking a question that ends with a quote, it goes outside the quote. Use single quotation marks for quotes within quotes.
- “Have you heard All These Things I Have Done?”
- Brandon Flowers of The Killers said, “I was inspired and on a roll when I wrote, ‘I got soul, but I’m not a soldier.'”
People, places, and things
↑ Back to topCompany names and products
Use brand identity names and products as written on official websites.
- Pull&Bear
- GitHub
- 23andMe
Refer to a company or product as “it”, not “they”.
- Woo is, not Woo are.
File extensions
A file extension type should be all uppercase without periods. Add a lowercase “s” to make it plural.
- HTML
- CSV
- PDFs
A specific file should have a lowercase extension type:
- dancingmochi.gif
- CharlieDataReport2023.pdf
- kevinsingswonderwall.mp3
Names and titles
The first mention of a person should include their first and last name. Second and consecutive mentions can use the first name only. Capitalize job titles, the names of teams, and departments.
- Matt Mullenweg
- Happiness Engineers or HEs
- Team Alpha
- Legal
Pronouns
Use “he/him/his”, “she/her/hers“, or “they/them/theirs” as appropriate. Don’t use “one” as a pronoun. Use “they/them/theirs” when referring to a group.
Quotes
Use present tense when quoting someone.
- “I love that WooCommerce is free and flexible,” says Ronald.
Schools
The first time you mention a school, college, or university in a piece of writing, refer to it by its full official name. On all other mentions, use its more common abbreviation.
- Georgia Institute of Technology
- Georgia Tech
- University of Cape Town
- UCT
Cities, states, and countries
Spell out all city and US state names — don’t abbreviate city names. On the first mention, write out the United States; for subsequent mentions, use US.
- Raleigh, North Carolina
- Illinois, United States
The same applies to other countries or federations with a common abbreviation, such as the European Union (EU) and the United Kingdom (UK).
URLs and websites
Capitalize website and web publication names; don’t italicize them. Avoid writing out URLs and omit https://www. where possible.
Slang and jargon
↑ Back to topWrite in plain English. The text should be universally understood, with potential for translation. Briefly define technical terms when needed.
Text formatting
↑ Back to topUse italics to indicate the title of a book, movie, or album.
- The Oren Klaff book Pitch Anything is on sale for 259.99 ZAR.
- David bought The National’s Boxer on vinyl.
Avoid:
- Underlining text — this is reserved for hyperlinks.
- A mix of italic, bold, caps, and underline.
Left-align paragraph text, never center or right-align. Leave a single space between sentences, never two.
Structure and readability
Avoid large blocks of text to keep information skimmable and digestible.
Consider using bulleted or numbered lists when listing three or more items in a paragraph. Avoid multiple nested sub-bullets, as this can become visually overwhelming for readers.