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.
- First use: Payment Card Industry Data Security Standard (PCI-DSS)
- Second use: PCI-DSS
- Active: Jon downloaded his extension files.
- Passive: The extension files were downloaded by Jon.
- Blog post and Documentation article titles: First word.
- Documentation headings (h2): Every word except prepositions and conjunctions.
- Product names: Every word except prepositions and conjunctions.
- Sentences: First word.
- Unordered/Bulleted lists – First word of each entry.
- “ecommerce” (not “eCommerce”)
- email address — email@example.com
- website URL — docs.woocommerce.com
- 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.
CurrencyUse 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
DatesSpell out the day of the week and month, using the format:
- Monday, December 12, 2016
DecimalsUse decimal points when a number is difficult to convert to a fraction, such as 3.141 or 98.5 or 0.29.
FractionsSpell out fractions: one-fourth
PercentSpell out the word ‘percent.’ Don’t use % symbol unless space is limited, e.g., for use on social media.
Phone numbersUse hyphens without spaces between numbers, not parentheses or periods. Use a country code for all countries.
Range and spanUse a hyphen to indicate a range or span of numbers: 20-30 days.
TemperatureUse the degree symbol and the capital C abbreviation for Celsius and capital F abbreviation for Fahrenheit.
TimesUse numbers and am or pm with a space and without periods.
- 7:00 am
- 7:30 pm
- 7:00-9:00 am and 7:00 am to 10:30 pm
- Eastern time: EDT or EST
- Central time: CDT or CST
- Mountain time: MDT or MST
- Pacific time: PDT or PST
- 80s and 90s
- 1900s and 1890s
AmpersandsAmpersands 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.
ApostrophesAn 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.
ColonsUse a colon to create a list.
- Aaron ordered three kinds of donuts: glazed, chocolate, and pumpkin.
CommasUse a serial comma, also known as an Oxford comma, when compiling a list.
- Jinny likes sunflowers, daisies, and peonies.
Dashes and hyphensUse a hyphen – without spaces on either side to link words, or indicate a span or range.
- first-time user
- 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.
EllipsesEllipses … can be used to indicate an indefinite ending to a sentence or to show words are omitted when used in brackets […] Use rarely.
Exclamation pointsUse 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
- 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 marksQuestion marks follow the same placement convention explained in Periods.
Quotation marksPeriods 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.’”
SemicolonsSemicolons 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.
Company names and productsUse brand identity names and products as written on official websites.
- UE Boom
- WooCommerce is, and not WooCommerce are.
A file extension type should be all uppercase without periods. Add a lowercase s to make plural.
Names and titlesFirst 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
PronounsUse 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.
QuotationsUse present tense when quoting someone.
- “I love that WooCommerce is free and flexible,” says Brent Jamison.
SchoolsThe 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 countriesSpell 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 websitesCapitalize the names of websites and web publications. Don’t italicize. Avoid writing out URLs; omit http://www when it’s necessary. Write in plain English. Text should be universally understood, with potential for translation. Briefly define technical terms when needed. 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.
- Underline formatting
- A mix of italic, bold, caps, and underline