Admin Punctuation

The following sections surface exceptions to the Associated Press (AP) Stylebook and summarize key stylebook elements to keep handy when writing content.

Sentences

All grammatically correct sentences end in punctuation, usually a period. When introducing a series or a list, end sentences with a colon.

Punctuation to Avoid

(;) Semicolons. Often, these awkwardly break sentences, and many users will find difficulty in understanding. Usually, a writer can simplify the sentence rather than use semicolons. Do not use in place of a conjunction.
Never use these punctuation types, unless they are included as part of a brand name:
- (&) Ampersands – international users don’t understand what ampersands mean
- (!) Exclamation points

Rules For …

Commas

Conjunctions. Use a comma before a conjunction to separate independent clauses (note: clauses have a subject and predicate) joined by conjunctions, including and, but, for, or, nor, so, and yet. See example:
- No – “Users go to the Cart and review their items. (No comma's needed, since no subject follows “and”.)"
- Yes – “Users go to the Cart, and they review their items.”
Use Oxford comma. Different from AP. We always use the Oxford or "serial" comma, which is the final comma in a list of items. Correct example: “Retain customers with custom registries, gift cards, and store credit.”
Parenthesis. For details, jump to the Parenthesis section.
Numbers, dates, addresses. For details, see Number Formats.
Introductory phrases. Use commas to set off introductory phrases. ... Commas can be omitted after short phrases as long as the meaning, transitioning between phrase and sentence, is clear. Correct example: "(After -or- Following -or- To follow) this section, read the Associated Press (AP) Stylebook’s commas entry."
Non-essential phrases. A non-essential phrase is a phrase that can be removed from a sentence without adversely affecting its meaning. "Which" is used for non-essential phrases, and "that" is used for essential phrases. See correct examples:
- Non-essential – "Promotions, which are set up with cart and catalog rules, are created in the Admin panel."
- Essential – "Promotions that are set up with catalog rules do not display in Cart."

Colon

Use to end a sentence before:

A complex series of items. Don't use a colon with a simple series. Also, consider using a list for a complex series of items. For details, see Lists section in Content Formats. See examples:
- No – “A shopping cart may include: pants, hats, and scarves."
- Yes – “A shopping cart may include pants, hats, and scarves.”
A bulleted list
A long quotation
An introductory, independent clause ... *Correct example:* "Here's an idea: Add a clause to a sentence."

Use between a title and a description or subtitle … Correct example: “Magento Live: Take Your Business to the Next Level”

Capitalization after a colon. When a complete sentence follows a colon, capitalize the first word of the following sentence. When a series or partial sentence follows a colon, do not capitalize.

Correct examples:

Complete sentence – "The company makes the following promise: This solution will improve your bottom line.”
Series – “There are three considerations: expense, time, and feasibility.”

Ellipsis

(…) Use with one space before and one space after. … Example: “The user will … complete a sentence.”

Use in:

Headers or sentences to introduce a bulleted list, when the preceding text and items complete a sentence.
Data labels to introduce a data field that completes a sentence.
Field labels to introduce a variable entry field that can be customized.

Em Dashes

(—) Use an em dash with a space on either side, as a longer breather between ideas. Do not use for ranges of numbers.

Correct example: The em dash — as noted in the stylebook — should have spaces before and after its placement.

Hyphens

(-) Use for:

Compound modifiers, but not common prefixes. … Correct examples: high-value item, hard-to-find item
Multiple modifiers. … Correct example: “high- and low-value items”
Exceptions include:
- Adverbs … Incorrect example: “highly-valued item”
- When not paired with a noun … Incorrect example: “The item is high-value.”
Do not use as a dash. See em dashes in previous entry.

Footnotes

(reference¹) Should use a number – not an asterisk or other symbols – here¹ and here², and the legal content that it references should be placed in the footer.

Money

For details, see the Money section in Number Formats.

Percentages

(%) Spell out “percent” unless space is constrained, as in a form or a data table. … Correct example: 23 percent

Parenthesis

Avoid using. Instead, use commas to set off parenthetical expressions or content.

Example:

No – Magento publishes User Guides (used primarily by Merchants).
Yes – Magento publishes User Guides, used primarily by Merchants.

For acronyms that aren’t referenced on first use, append them at the end of the term. … Correct example: World Wide Web Consortium (W3C)

Question Marks

(?) Generally avoid questions in content – use declarations.

Quotation Marks

(“) Always use double quotation marks when someone is speaking. Avoid “that” before quotes.