9.4 KiB
WooCommerce grammar, punctuation and capitalization guide
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@woo.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 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 – 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.
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.
- 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
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.