docs/best-practices/coding-standards/grammar-punctuation-capitalization.md
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.
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.
Spell out the full version on first mention with abbreviation or acronym in parentheses. Use the short version on second and consecutive mentions.
If the abbreviation or acronym is widely known, use it as is. For example: API, FAQ, HTML, PHP, SQL, SSL.
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.
Cases when we capitalize:
Cases when we use lower case:
[email protected]developer.woocommerce.comUse 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 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, and spell out numbers one through nine in all cases. Use numerals in all other cases.
Use a comma for numbers with more than three digits: 41,500, 170,000, 1,000,000 or 1 million.
Use currency codes and not only the symbol/sign when specifying dollars. Whole amounts need not have a decimal and two places.
When writing about other currencies, use the symbol/sign.
Spell out the day of the week and month, using the format:
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.' Don't use % 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.
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.
Use a hyphen between times to indicate a time period in am or pm. Use 'to' if the time period spans am and 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:
Abbreviate decades
Ampersands need only be used when part of an official company/brand name. Should not be substituted for 'and.'
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.
These are possessives: FAQ's questions, HE's weekly rotation. These are plural: FAQs and HEs.
Use a colon to create a list.
Use a serial comma, also known as an Oxford comma, when compiling a list.
Use common sense for other cases. Read the sentence out loud, and use a comma where clarity or pause may be needed.
Use a hyphen - without spaces on either side to link words, or indicate a span or range.
Use an em dash - without spaces on either side to indicate an aside.
Use a true em dash, not hyphens.
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.
Exclamation points follow the same placement convention explained in Periods.
Periods should be:
Examples
Question marks follow the same placement convention explained in Periods.
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.
Semicolons can be used to join two related phrases.
Use brand identity names and products as written on official websites.
Refer to a company or product as 'it' (not 'they').
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:
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.
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.
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.
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).
Capitalize 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.
Avoid:
Left-align text, never center or right-aligned.
Leave one space between sentences, never two.