General punctuation

This page contains rules about how to use punctuation in developer documentation, and especially the types of punctuation to avoid. Specialized punctuation is often a problem on screens, in screen readers, and in translation. To address this issue, these rules often recommend direct plain language to replace punctuation that is convenient for the writer but unnecessary for the reader.

The punctuation section of this guide also includes the following pages:

• Hyphens and dashes
• Quotation marks

Serial comma

punct-001 should GuidesAPI docsMarketingBlog

Use the Oxford (serial) comma before the final conjunction in a list of three or more items.

Examples

• ✓ The SDK supports Python, Ruby, and Go.
• ✗ The SDK supports Python, Ruby and Go.

Rationale

An Oxford comma separates the last two items in a list, so readers don’t mistake them for a single combined item.

One space after a period

punct-018 should GuidesAPI docsMarketingBlog

Use one space, not two, after a period.

Examples

• ✓ Run the tests. Then deploy (this example uses one space after the period).
• ✗ Run the tests. Then deploy (this example uses two spaces after the period).

Rationale

Adding two spaces after the ending punctuation of a sentence is a typewriter convention. Rendered text collapses them, and in formats that preserve whitespace they leave an uneven gap.

Use semicolons sparingly

punct-014 should GuidesAPI docsMarketingBlog

Use semicolons sparingly. Prefer shorter sentences or 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

A sentence with several semicolon-linked clauses can be difficult to scan. Separate sentences or a list make each point easier to identify.

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 don’t 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

Outside a quotation, an ellipsis can suggest omitted steps, an incomplete list, hesitation, or an unfinished thought. When a list is intentionally partial, introduce it with such as (list-010) instead.

Omit ellipses from UI names

punct-012 should GuidesAPI docsMarketingBlog

When an ellipsis appears in UI, don’t reproduce it in instructions describing that UI element.

Examples

• ✓ Select Save as.
• ✗ Select Save as….

Rationale

An ellipsis in a UI label signals that another step or dialog follows. It describes the control’s behavior rather than naming the control, so an instruction can omit it.

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

Rationale

Spaces separate an ellipsis from the words that remain in a quotation. Without the spaces, the ellipsis can look like part of either word.

No slashes as a substitute for or

punct-015 should GuidesAPI docsMarketingBlog

In body text, don’t use a slash to replace or. Write or, or and when that is the meaning.

Examples

• ✓ Restart the server or the worker.
• ✗ Restart the server/worker.

Rationale

A slash between words can mean and, or, or a ratio. Writing the intended conjunction removes the ambiguity.

No slashes in dates

punct-016 should GuidesAPI docsMarketingBlog

Don’t use slashes in dates. Use an unambiguous date format instead.

Examples

• ✓ Support for v1 ends on June 30, 2026.
• ✗ Support for v1 ends on 6/30/2026.

Rationale

The order of the month and day in a slash date differs by region. Spelling out the month or using an ISO 8601 date makes the order explicit. For more information about date formats, see date and time.

No slash abbreviations

punct-025 should GuidesAPI docsMarketingBlog

Don’t use abbreviations that rely on slashes, such as c/o and w/. Spell the words out.

Examples

• ✓ The proxy works with or without authentication.
• ✗ The proxy works w/ or w/o authentication.

Rationale

Slash abbreviations such as w/ are informal and can be unfamiliar to readers. The full words are easier to recognize and translate.

Use 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

An exclamation point adds excitement or urgency that concept and reference documentation rarely need. Reserving it for tutorial milestones keeps the emphasis noticeable.

Parentheses for incidental information only

punct-026 should GuidesAPI docsMarketingBlog

Avoid placing important information in parentheses. Consider whether the parentheses are necessary and whether commas or separate sentences serve better. For examples, prefer such as or for example in the sentence over a parenthetical list.

Examples

• ✓ Retries are safe because the call is idempotent.
• ✗ Retries are safe (the call is idempotent).

Rationale

Parentheses signal that the enclosed content is incidental. A reader who scans past a parenthetical can miss an important condition or explanation.

Match punctuation to 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. Punctuation that is part of the element keeps the element’s style. This exception applies when the user must type the punctuation or when a code element ends with it. The rule doesn’t cover the label of a callout, such as a note or a warning, whose form depends on the documentation platform.

Examples

• ✓ Set timeout, then restart the service.
• ✗ Set timeout, then restart the service.
• ✓ End each statement with ;, as in count = 0;.
• ✓ In the Name box, enter a name.
• ✗ In the Name, box, enter a name.

Rationale

When sentence punctuation uses the same style as adjacent code or a UI label, readers can mistake it for part of the element. Matching the body-text style separates the punctuation from the element. A character that the reader types, such as a statement terminator or the colon in a key, remains in code font. The documentation platform can render a callout as a bold label with a colon, an icon, or a titled box, so the label’s form isn’t a punctuation decision.

Applicable rules from other topics

• Introducing a list list-004 should
• Clause introductions list-012 should

Deprecated rules

• punct-009 (retired 2026-09-18): “The text before a colon that introduces a list must be a grammatically complete sentence.” The guide accepts a clause before a list colon (list-004); what the clause needs is context, not a finite verb, and list-012 states it. Its example, “The CLI supports:”, is list-012’s ✗.

• punct-002 (retired 2026-08-19): “Use em dashes without spaces on either side to set off parenthetical phrases or interruptions.” Superseded by punct-028, which says not to use em dashes at all.

• punct-003 (retired 2026-08-19): “Do not use a hyphen or double hyphen in place of an em dash.” Superseded by punct-028: nothing is written in place of an em dash; the sentence is rewritten with commas, parentheses, a colon, or a period.