woocommerce/docs/quality-and-best-practices/grammar-punctuation-capitalization.md

---
post_title: WooCommerce grammar, punctuation and capitalization guide
menu_title: Grammar, punctuation and capitalization
tags: reference
---

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

**Be democratic**. Some people read every word. Some scan and search or prefer video. Help everyone.

**Be focused**. Lead with the most important information in sentences, paragraphs, and sections.

**Be concise**. Use plain language and brief sentences.

**Be consistent**. Follow our guidelines and style tips.

**Be specific**. Communicate crystal clear. Trim the fat.

## Guidelines

### Abbreviations and acronyms

Spell out the full version on first mention with abbreviation or acronym in parentheses. Use the short version on second and consecutive 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. For example: API, FAQ, HTML, PHP, SQL, SSL.

### Active voice

With active voice, the subject in the sentence performs the action. With passive voice, the subject in the sentence has the action done unto it.

- Active: Jon downloaded his extension files.
- Passive: The extension files were downloaded by Jon.

### Capitalization

Cases when we capitalize:

- Blog post and documentation article titles: First word.
- Documentation headings (h2): Use sentence case (not title case) for docs titles and subheadings. 
- Product names: Every word except prepositions and conjunctions.
- Sentences: First word.
- Unordered/Bulleted lists - First word of each entry.

Cases when we use lower case:

- "ecommerce" (not "eCommerce")
- email address - `info@woocommerce.com`
- website URL - `developer.woocommerce.com`

### Contractions

Use with discretion. Contractions, such as I'm and there's, give writing an informal and conversational feel, but may be inappropriate if content is being translated. For example, sometimes the not in don't is ignored by online translators.

### Emoji

Emoji can add subtle emotion and humor or bring visual attention to your content. Use rarely and intentionally.

### Numbers

Spell out a number at the start of a sentence, and spell out numbers one through nine in all cases. Use numerals in all other cases.

- Ten products will launch in June. Not: 10 products will launch in June.
- Lance ran a marathon and won third place in his age group.
- I bought five hammers and 21 types of nails for the building project.
- There were 18 kinds of beer on tap at the pub.

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 only the symbol/sign when specifying dollars. Whole amounts need not have a decimal and two places.

- USD $20
- CAD $19.99
- AUD $39.50

When writing about other currencies, use the symbol/sign.

- €995
- ¥5,000
- £18.99

#### Dates

Spell out the day of the week and month, using the format:

- Monday, December 12, 2016

#### Decimals

Use decimal points when a number is difficult to convert to a fraction, such as 3.141 or 98.5 or 0.29.

#### Fractions

Spell out fractions: one-fourth

#### Percent

Spell out the word 'percent.' Don't use % symbol unless space is limited, e.g., for use on social media.

#### Phone numbers

Use hyphens without spaces between numbers, not parentheses or periods. Use a [country code](https://countrycode.org/) for all countries.

- +1-555-867-5309
- +34-902-1899-00

#### Range and span

Use a hyphen to indicate a range or span of numbers: 20-30 days.

#### Temperature

Use the degree symbol and the capital C abbreviation for Celsius and capital F abbreviation for Fahrenheit.

- 27°C
- 98°F

#### Times

Use numbers and am or pm with a space and without periods.

- 7:00 am
- 7:30 pm

Use a hyphen between times to indicate a time period in am or pm. Use 'to' if the time period spans am and pm.

- 7:00-9:00 am and 7:00 am to 10:30 pm

Specify a time zone when writing about an event with potential attendees worldwide. Automattic uses Coordinated Universal Time (UTC).

Abbreviate U.S. time zones:

- Eastern time: EDT or EST
- Central time: CDT or CST
- Mountain time: MDT or MST
- Pacific time: PDT or PST

#### Years

Abbreviate decades

- 80s and 90s
- 1900s and 1890s

### Punctuation

#### Ampersands

Ampersands need only be used when part of an official company/brand name. Should not be substituted for 'and.'

- Ben & Jerry's
- Andre, Timo, and Donny 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 's. If a word ends in s and is plural, add an apostrophe.

- A teammate borrowed Sam's bike.
- A teammate borrowed Chris's bike.
- Employees hid the office managers' pens.

These are possessives: FAQ's questions, HE's weekly rotation. These are plural: FAQs and HEs.

#### Colons

Use a colon to create a list.

- Aaron ordered three kinds of donuts: glazed, chocolate, and pumpkin.

#### Commas

Use a serial comma, also known as an Oxford comma, when compiling a list.

- Jinny likes sunflowers, daisies, and peonies.

Use common sense for other cases. Read the sentence out loud, and use a comma where clarity or pause may be needed.

#### Dashes and hyphens

Use a hyphen - without spaces on either side to link words, or indicate a span or range.

- first-time user
- Monday-Friday

Use an em dash - without spaces on either side to indicate an aside.

Use a true em dash, not hyphens.

- Multivariate testing-just one of our new Pro features-can help you grow your business.
- Austin thought Brad was the donut thief, but he was wrong-it was Lain.

#### Ellipses

Ellipses ... can be used to indicate an indefinite ending to a sentence or to show words are omitted when used in brackets [...] Use rarely.

#### Exclamation points

Use an exclamation point rarely and use only one.

Exclamation points follow the same placement convention explained in Periods.

#### Periods

Periods 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

- Jake said, "I had the best day ever."
- She went to the supermarket (and to the nail salon).
- My mom loves pizza and beer. (Beer needs to be cold and dark.)

#### Question marks

Question marks follow the same placement convention explained in Periods.

#### Quotation marks

Periods and commas go 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.

- Who sings, "All These Things That I've 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.'"

#### 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 the UK.

### People, places, and things

#### Company names and products

Use brand identity names and products as written on official websites.

- Pull&Bear
- UE Boom

Refer to a company or product as 'it' (not 'they').

- WooCommerce is, and not WooCommerce are.

#### File extensions

A file extension type should be all uppercase without periods. Add a lowercase s to make plural.

- HTML
- JPEG
- PDF

A specific file should have a lowercase extension type:

- dancingcat.gif
- SalesReport2016.pdf
- firethatcannon.mp3

#### Names and titles

First mention of a person should include their first and last name. Second and consecutive mentions can use first name only.

Capitalize job titles, the names of teams, and departments.

- Happiness Engineers or HEs
- Team Apollo
- Legal

#### Pronouns

Use he/him/his and she/her/her as appropriate. Don't use "one" as a pronoun. Use they/them/their if gender is unknown or when referring to a group.

#### Quotations

Use present tense when quoting someone.

- "I love that WooCommerce is free and flexible," says Brent Jamison.

#### 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
- Georgia State University, GSU

#### States, cities, and countries

Spell out all city and state names. Don't abbreviate city names.

On first mention, write out United States. For further mentions, use U.S. The same applies to other countries or federations with a common abbreviation, such as European Union (EU) and United Kingdom (UK).

#### URLs and websites

Capitalize the names of websites and web publications. Don't italicize.

Avoid writing out URLs; omit `http://www` when it's necessary.

### Slang and jargon

Write in plain English. Text should be universally understood, with potential for translation. Briefly define technical terms when needed.

### Text formatting

Use italics to indicate the title of a book, movie, or album.

- The Oren Klaff book Pitch Anything is on sale for USD $5.99.

Avoid:

- Underline formatting
- A mix of italic, bold, caps, and underline

Left-align text, never center or right-aligned.

Leave one space between sentences, never two.