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.

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. Avoid jargon and clichés.

Be consistent. Follow our guidelines and style tips.

Be specific. Communicate clearly and succinctly.

Guidelines

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.

Active voice

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.

Capitalization

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.

Lower case

  • email address — info@woocommerce.com
  • website URL — docs.woocommerce.com
  • Words listed at Glossary (add link)

Contractions

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

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. 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.

Currency

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.

  • €995
  • ¥5,000
  • £18.99

Dates

Spell out the day of the week and month, using the following 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.” Avoid using the % 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 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 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

Years

Abbreviate decades

  • 80s and 90s
  • 1900s and 1890s

Punctuation

Ampersands

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.

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 — 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

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 for emphasis.

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 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

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.

  • Nestlé
  • 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
  • puppiesarecute.mp3

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
  • 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 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.

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

Always Left-align text, never center or right-aligned. Leave one space between sentences, never two.