punct-001 should GuidesAPI docsMarketingBlog Use the Oxford (serial) comma before the final conjunction in a list of three or more items.
Punctuation
These rules cover the punctuation marks that come up most in developer docs — commas, colons and semicolons, dashes and hyphens, quotation marks, ellipses, and slashes — plus the spacing and font styling around them. Two hyphenation exceptions for compound modifiers (-ly adverbs and predicate position) live on the compound modifiers page.
Serial comma
Section titled “Serial comma”Examples
- ✓ The SDK supports Python, Ruby, and Go.
- ✗ The SDK supports Python, Ruby and Go.
Rationale
The final comma keeps the last two items distinct, preventing a reading where they merge into one.
One space after a period
Section titled “One space after a period”punct-018 should GuidesAPI docsMarketingBlog Use one space, not two, after a period.
Examples
- ✓ Run the tests. Then deploy.
- ✗ Run the tests. Then deploy.
Rationale
One space after a period is the current typesetting standard; two is a typewriter holdover.
Colons after complete sentences
Section titled “Colons after complete sentences”punct-009 should GuidesAPI docsMarketingBlog The introductory phrase before a colon that introduces a list must be a grammatically complete sentence.
Examples
- ✓ The CLI supports the following commands:
- ✗ The CLI supports:
Semicolons sparingly
Section titled “Semicolons sparingly”punct-014 should GuidesAPI docsMarketingBlog Use semicolons sparingly; prefer breaking sentences into shorter ones or converting to lists, but permit semicolons between closely related independent clauses and in complex series with internal punctuation.
Examples
- ✓ The build failed. Check the logs for details.
- ✗ The build failed; check the logs for details; the most common cause is a missing dependency.
Rationale
Semicolons join dense clauses that a reader often parses more easily as separate sentences or a list.
Em dashes without spaces
Section titled “Em dashes without spaces”punct-002 should GuidesAPI docsMarketingBlog Use em dashes without spaces on either side to set off parenthetical phrases or interruptions.
Examples
- ✓ The request fails—usually with a 429—when you exceed the rate limit.
- ✗ The request fails — usually with a 429 — when you exceed the rate limit.
Em dashes, not hyphens
Section titled “Em dashes, not hyphens”punct-003 should GuidesAPI docsMarketingBlog Do not use a hyphen or double hyphen in place of an em dash.
Examples
- ✓ Retries are automatic—no configuration needed.
- ✗ Retries are automatic — no configuration needed.
No en dashes
Section titled “No en dashes”punct-010 should GuidesAPI docsMarketingBlog Do not use en dashes; use a hyphen or the word ‘to’ for number ranges.
Examples
- ✓ Ports 3000 to 3005 are reserved.
- ✗ Ports 3000–3005 are reserved.
Rationale
En dashes are easy to confuse with hyphens and minus signs and are hard to type, so a hyphen or “to” is clearer for ranges.
Hyphens without spaces
Section titled “Hyphens without spaces”punct-023 should GuidesAPI docsMarketingBlog Do not place spaces on either side of a hyphen, except in suspended hyphens where a space may follow (but not precede) the hyphen.
Examples
- ✓ Use a read-only token.
- ✗ Use a read - only token.
- ✓ This applies to two- and three-node clusters.
Hyphens in compound modifiers
Section titled “Hyphens in compound modifiers”punct-004 should GuidesAPI docsMarketingBlog When two or more words together modify a noun, hyphenate them (a 30-second timeout, a high-priority task). Don’t hyphenate when the unit is an abbreviation or symbol (a 16 GB drive) or when the compound follows the noun in predicative position.
Examples
- ✓ Cancel the high-priority task first.
- ✗ Cancel the high priority task first.
Rationale
A hyphen signals that two or more words act as a single modifier, so “a 30-second timeout” reads as one idea rather than separate words. Abbreviated units already read as a unit and take no hyphen (“a 16 GB drive”), and the hyphen is unneeded after the noun.
Hyphens with spelled-out units
Section titled “Hyphens with spelled-out units”punct-020 should GuidesAPI docsMarketingBlog Hyphenate a compound modifier when its unit is spelled out (a 5-foot cable), but not when the unit is an abbreviation or symbol (a 5 ft cable).
Examples
- ✓ Connect a 5-foot cable.
- ✗ Connect a 5 foot cable.
- ✓ Connect a 5 ft cable.
- ✗ Connect a 5-ft cable.
Rationale
The hyphen marks a spelled-out unit as part of a single modifier (“a 5-foot cable”), while an abbreviation already reads as a unit and needs none (“a 5 ft cable”).
Hyphens in location compounds
Section titled “Hyphens in location compounds”punct-021 should GuidesAPI docsMarketingBlog Hyphenate location compounds such as ‘lower-left corner’ and ‘top-right portion’.
Examples
- ✓ Select the icon in the lower-left corner.
- ✗ Select the icon in the lower left corner.
Rationale
“Lower-left” acts as a single modifier, so the hyphen keeps it reading as one direction.
Hyphens with prefixes
Section titled “Hyphens with prefixes”punct-005 should GuidesAPI docsMarketingBlog Write prefixed words as a single closed-up word when the closed form is established usage (email, runtime, subdomain, nonprofit). Use a hyphen when the prefix is cross-, self-, all-, or ex-; when the base word is a proper noun; when the closed form is ambiguous, hard to read, or a different word; or when the compound isn’t well established yet. When in doubt, check the word list.
Examples
- ✓ Add a subdomain for each environment.
- ✗ Add a sub-domain for each environment.
- ✓ Create a cross-region replica.
- ✗ Create a crossregion replica.
Rationale
Established prefixed words read as single words (“email”, “runtime”, “subdomain”), so closing them up matches how developers already write them. A hyphen stays where the closed form is ambiguous, hard to read, or a different word, or where the prefix is cross-, self-, all-, or ex-.
Closed compound nouns
Section titled “Closed compound nouns”punct-024 should GuidesAPI docsMarketingBlog Prefer the closed (one-word) form for compound nouns unless a hyphenated or open form is established by convention or the word list.
Examples
- ✓ Check the changelog before upgrading.
- ✗ Check the change-log before upgrading.
Rationale
Established compounds read as one word, so closing them up matches convention; the word list settles contested cases.
Straight quotation marks in code
Section titled “Straight quotation marks in code”punct-006 should GuidesAPI docsMarketingBlog Use straight quotation marks in code samples and code font regardless of the convention used in body text.
Examples
- ✓
print("Hello") - ✗
print(“Hello”)
Rationale
Straight quotes in code are what compilers and shells expect; a curly quote copied from docs breaks the code.
Periods and commas inside quotation marks
Section titled “Periods and commas inside quotation marks”punct-007 should GuidesAPI docsMarketingBlog Place periods and commas inside closing quotation marks in body text.
Examples
- ✓ The spec calls this “the happy path.”
- ✗ The spec calls this “the happy path”.
Punctuation outside quoted literals
Section titled “Punctuation outside quoted literals”punct-008 should GuidesAPI docsMarketingBlog When a literal string or keyword is in quotation marks, place any surrounding punctuation outside the quotation marks.
Examples
- ✓ Set the status to “active”.
- ✗ Set the status to “active.”
Rationale
Keeping punctuation outside a quoted literal prevents a reader from thinking the period is part of the value.
Double, not single, quotation marks
Section titled “Double, not single, quotation marks”punct-022 should GuidesAPI docsMarketingBlog Do not use single quotation marks in body text except when nesting a quotation inside another quotation or in code examples that require them.
Examples
- ✓ The response includes the note “retry later.”
- ✗ The response includes the note ‘retry later.’
Rationale
Single quotes in body text are easily confused with apostrophes, so double quotes are unambiguous, with single quotes reserved for nesting and code.
Ellipses only in quotations
Section titled “Ellipses only in quotations”punct-011 should GuidesAPI docsMarketingBlog Avoid ellipses in technical documentation; use them only in quoted text to indicate omitted material, and do not use them at the beginning or end of a quotation.
Examples
- ✓ You can configure timeouts, retries, and backoff.
- ✗ You can configure timeouts, retries, backoff…
Rationale
Ellipses are vague in technical writing, so they belong only in quotations to mark omitted text.
Omit ellipses from UI names
Section titled “Omit ellipses from UI names”punct-012 should GuidesAPI docsMarketingBlog When an ellipsis appears in UI, do not reproduce it in instructions describing that UI element.
Examples
- ✓ Select Save as.
- ✗ Select Save as….
Rationale
The ellipsis on a UI label is not part of the label’s name, so instructions omit it.
Spaces around ellipses in quotations
Section titled “Spaces around ellipses in quotations”punct-013 should GuidesAPI docsMarketingBlog In quoted material, insert one space before and after an ellipsis that replaces text within a sentence.
Examples
- ✓ The changelog notes that “the parser … now streams input.”
- ✗ The changelog notes that “the parser…now streams input.”
No slashes as a substitute for or
Section titled “No slashes as a substitute for or”punct-015 should GuidesAPI docsMarketingBlog Do not use slashes as a substitute for ‘or’ in body text; write out ‘or’ or ‘and’ instead.
Examples
- ✓ Restart the server or the worker.
- ✗ Restart the server/worker.
Rationale
A slash between words is ambiguous about whether it means and, or, or a ratio, while the word is clear.
No slashes in dates
Section titled “No slashes in dates”punct-016 should GuidesAPI docsMarketingBlog Do not use slashes in date formats; use a dedicated date format instead.
Examples
- ✓ Support for v1 ends on June 30, 2026.
- ✗ Support for v1 ends on 6/30/2026.
Rationale
Slash dates are region-ambiguous, while a dedicated date format is not.
No slash abbreviations
Section titled “No slash abbreviations”punct-025 should GuidesAPI docsMarketingBlog Do not use abbreviations that rely on slashes (c/o, w/); spell the words out.
Examples
- ✓ The proxy works with or without authentication.
- ✗ The proxy works w/ or w/o authentication.
Rationale
Slash abbreviations like “w/” are informal and easy to miss, so spelling them out is clear.
Exclamation points sparingly
Section titled “Exclamation points sparingly”punct-017 should GuidesAPI docsMarketingBlog Use exclamation points sparingly; avoid them in concept and reference documentation; they are acceptable in tutorials to mark major milestones and in code when required by syntax.
Examples
- ✓ The endpoint returns the user’s profile.
- ✗ The endpoint returns the user’s profile!
Rationale
Exclamation points read as hype in reference material, so reserving them keeps their emphasis meaningful.
Parentheses for incidental information only
Section titled “Parentheses for incidental information only”punct-026 should GuidesAPI docsMarketingBlog Avoid placing important information in parentheses; consider whether parentheses are necessary and whether commas, dashes, or separate sentences would serve better.
Examples
- ✓ Retries are safe because the call is idempotent.
- ✗ Retries are safe (the call is idempotent).
Rationale
Parentheses signal that content is skippable, so important information hidden there may be missed.
Punctuation in body-text style
Section titled “Punctuation in body-text style”punct-019 should GuidesAPI docsMarketingBlog Format punctuation in the same font style as the surrounding body text, not the style of the element it follows, unless the punctuation is part of what the user must type or is part of the element itself.
Examples
- ✓ Set
timeout, then restart the service. - ✗ Set
timeout,then restart the service.
Rationale
Punctuation styled like the code element beside it looks like part of that element, so matching the surrounding text keeps it clearly punctuation.
Hyphenate z- prefixed terms
Section titled “Hyphenate z- prefixed terms”punct-027 should GuidesAPI docsMarketingBlog Hyphenate z- prefixed terms such as z-index, z-order, and z-axis rather than closing them up.
Examples
- ✓ Set the
z-indexso the modal stacks above the toolbar. - ✗ Set the
zindexso the modal stacks above the toolbar.
Rationale
The single-letter z- prefix reads as part of the following word when closed up, so the hyphen keeps the term legible and matches its conventional form.