Following grammar, punctuation, and style guidelines ensures consistency across our documentation and helps build trust with users. Users have a better experience when they know what to expect and where to find the information they need.
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. Avoid jargon and clichés.
Be consistent. Follow our guidelines and style tips.
Be specific. Communicate clearly and succinctly.
Abbreviations and acronyms
Spell out the full version of a term on the first mention with abbreviation or acronym in parentheses. Use the abbreviation or acronym on subsequent mentions. Here are a couple of examples:
- 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, and SSL.
With the active voice, the subject of the sentence performs the action. With the passive voice, the subject in the sentence has the action done to it.
- Active: Jon downloaded his extension files.
- Passive: The extension files were downloaded by Jon.
Cases when we capitalize:
- Use title case for blog post titles and documentation titles.
- Documentation headings (h2): Every word except prepositions and conjunctions.
- Product names: Every word except prepositions and conjunctions.
- Unordered/Bulleted lists — First word of each entry.
- email address — email@example.com
- website URL — docs.woocommerce.com
- Words listed at Glossary (add link)
Use with discretion. Contractions, such as I’m and there’s, give writing an informal and conversational feel, but maybe inappropriate if the content is being translated. For example, sometimes the “not” in “don’t” is ignored by online translators.
Emoji can add subtle emotion and humor or bring visual attention to your content. Use rarely and intentionally.
Spell out a number at the start of a sentence. Spell out numbers one through nine in all cases. Use numerals for numbers 10 and up.
- 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 soap at the store.
Use a comma for numbers with more than three digits: 41,500, 170,000, 1,000,000, or 1 million.
Use currency codes and 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.
Spell out the day of the week and month, using the following format:
- Monday, December 12, 2016
Use decimal points when a number is difficult to convert to a fraction, such as 3.141 or 98.5 or 0.29.
Spell out fractions: one-fourth
Spell out the word “percent.” Avoid using the % symbol unless space is limited, e.g., for use on social media.
Use hyphens without spaces between numbers, not parentheses or periods. Use a country code for all countries.
Range and span
Use a hyphen to indicate a range or span of numbers: 20-30 days.
Use the degree symbol and the capital C abbreviation for Celsius and capital F abbreviation for Fahrenheit.
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 worldwide attendees. 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
- 80s and 90s
- 1900s and 1890s
Ampersands need only be used when part of an official company/brand name. Ampersands should not be substituted for the word “and.”
- Ben & Jerry’s
- Andre, Timo, and Donny went to a football game at Camp Nou.
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.
Use a colon to create a list.
- Aaron ordered three kinds of donuts: glazed, chocolate, and pumpkin.
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
Use an em dash — with spaces on either side to indicate an aside.
Use a true em dash — not hyphens – or –.
- 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 … can be used to indicate an indefinite ending to a sentence or to show words are omitted when used in brackets […] Use rarely.
Use an exclamation point rarely and use only one for emphasis.
Exclamation points follow the same placement convention explained in 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 marks follow the same placement convention explained in Periods.
Periods and commas appear inside 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 can be used to join two related phrases.
- Their debut solo album hit the Top 10 in 20 countries; it went platinum in the UK.
People, places, and things
Company names and products
Use brand identity names and products as written on official websites.
- UE Boom
Refer to a company or product as “it” (not “they”).
- WooCommerce is, and not WooCommerce are.
A file extension type should be all uppercase without periods. Add a lowercase s to make plural.
A specific file should have a lowercase extension type:
Names and titles
The first mention of a person should include their first and last name. Subsequent mentions can use their first name only.
Capitalize job titles, the names of teams, and departments.
- Happiness Engineers or HEs
- Team Apollo
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.
Use present tense when quoting someone.
- “I love that WooCommerce is free and flexible,” says Brent Jamison.
The first time you mention a school, college, or university in a piece of writing, refer to it by its full official name with its abbreviation in parentheses. On subsequent 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 the first mention, write out the United States. On subsequent mentions, use the abbreviation, U.S. 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 the names of websites and web publications. Don’t italicize.
Avoid writing out URLs; omit http://www when it’s necessary.
Slang, jargon, and clichés
Write in plain English. The text should be clear and easy to translate. 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
Always Left-align text, never center or right-aligned. Leave one space between sentences, never two.