Punctuation rules

Punctuation in documentation is not ornamental — it shapes how sentences are read, how lists are structured, and whether instructions are clear or ambiguous. This article covers the punctuation decisions that arise most frequently in documentation, with clear rulings for each.

Periods

Use a period at the end of every complete sentence, including in list items that are complete sentences. Do not use a period after a list item that is a word or short phrase (not a sentence).

List parallelism

Beyond individual punctuation, every item in a list should share the same grammatical form — all complete sentences, all sentence fragments, or all noun phrases, not a mix. A list that switches between forms is harder to scan, even if each item is individually punctuated correctly.

Commas

The serial comma (Oxford comma)

Always use the serial comma — the comma before the final item in a list of three or more. This removes ambiguity in lists where the final two items could be misread as a pair.

Commas in compound sentences

Use a comma before a coordinating conjunction (and, but, or, nor, for, yet, so) that joins two independent clauses.

Correct: "Click Save, and the record will update automatically."
Correct: "You can export the file, or you can share it directly from the dashboard."

Commas after introductory elements

Use a comma after introductory words, phrases, and clauses that precede the main clause.

Correct: "After you save the file, the upload begins automatically."
Correct: "To access this feature, you must have administrator permissions."

Semicolons

Semicolons have a narrow but legitimate place in documentation. Use one in exactly two situations:

• Joining two closely related independent clauses without a conjunction, when the relationship between them is direct enough that a period would break it unnecessarily: "The export failed; the file exceeded the size limit."
• Separating list items that themselves contain commas, to avoid ambiguity about where one item ends and the next begins: "The release includes three fixes: a login issue affecting Safari, version 15 and later; a display bug in the mobile app; and a delay in email notifications."

Outside of these two cases, prefer a period or a comma. Semicolons used to link loosely related ideas ("Click Save; this is important") usually signal that a sentence should be split or restructured instead.

Colons

Use a colon to introduce a list, a code block, or an explanation that follows directly from the sentence before it. The sentence before the colon should be a complete sentence.

Correct: "The dashboard shows three types of data: page views, session duration, and search terms."
Incorrect: "The dashboard shows: page views, session duration, and search terms." (The sentence before the colon is not complete.)

Use a colon to introduce a code block or an example that follows a complete sentence.

Em Dashes and En Dashes

Em dash (—)

Use an em dash to set off a parenthetical phrase when you want to give it more emphasis than parentheses would. Do not use spaces around the em dash.

Correct: "The export feature — available on all plans — produces a ZIP file."
Incorrect: "The export feature - available on all plans - produces a ZIP file." (Hyphens are not em dashes.)

Do not overuse em dashes. If an article has an em dash in every other sentence, rewrite the sentences to stand alone.

En dash (–)

Use an en dash between numbers in a range: pages 12–18, 2019–2024, 10–20 minutes. Do not use a hyphen for ranges.

Hyphens

Hyphens join compound modifiers before a noun. They are not used when the compound modifier follows the noun.

Do not hyphenate compound modifiers that include an adverb ending in -ly: "a clearly written article," not "a clearly-written article."

Quotation Marks

Use quotation marks for direct quotations and for titles of short works. Do not use quotation marks to call attention to a word or phrase — use bold or italic instead, as appropriate.

In American English, periods and commas go inside closing quotation marks. Colons and semicolons go outside.

Use double quotation marks (" ") as the primary style. Use single quotation marks (' ') only for a quotation within a quotation.

Do not use quotation marks around UI element names. Use bold instead: click the Save button, not click the "Save" button.

Parentheses

Use parentheses sparingly in documentation. They can make sentences harder to read, especially in instructional content. If the information in parentheses is important, promote it out of the parentheses. If it is not important, remove it.

Acceptable uses of parentheses in documentation:

• Abbreviations introduced after the full form: "Single Sign-On (SSO)"
• Optional steps: "Click Back (optional) to review your previous entries."
• Keyboard shortcuts: "Press Ctrl+S (Windows) or Cmd+S (Mac) to save."

Brackets for Placeholders

Use square brackets to mark placeholder text that a writer or reader is meant to replace with specific information — for example, in a scope-defining sentence or a templated instruction: "This article explains how to [task] for [audience], starting from [prerequisite state]."

Never let bracketed placeholder text reach a published, reader-facing article. Brackets belong in drafting templates and internal scope statements only; if real content is genuinely unknown at publish time, resolve it, remove the sentence, or flag it explicitly for review rather than shipping a bracket to the reader.

Ellipses

Ellipses (…) have a narrow, mostly UI-driven use in documentation: describing in-progress states shown in the product itself, such as a button labeled "Saving…" or "Loading…" Reproduce the label exactly as it appears in the UI.

Avoid ellipses in regular prose to indicate a trailing or unfinished thought — in documentation, an unfinished thought is a sign the sentence needs to be completed or cut, not punctuated around.

The Ampersand

Use "and" in prose. Reserve the ampersand (&) for cases where it appears as part of an exact UI label ("Save & Close") or a proper name/brand term that uses it natively. Do not use "&" as a shorthand for "and" in sentences, headings, or list items you are writing yourself.

Apostrophes

Use apostrophes for contractions and to show possession. Do not use apostrophes to form plurals.

Note on contractions: contractions are acceptable in documentation that uses a conversational tone. "You can't delete this item" is fine in casual, friendly documentation. In more formal or technical contexts, spell out the full form: "You cannot delete this item."

Punctuation with Inline Code

When a sentence ends with a term rendered in inline code formatting (backticks or a monospace UI element name), keep the closing punctuation outside the code span unless the punctuation is itself part of the code value.

Correct: Set the value to true.
Incorrect: Set the value to true. (the period is not part of the value and should not appear inside the code formatting)

If the code term itself ends in punctuation that's part of the syntax — a closing parenthesis in a function call, for instance — that punctuation stays inside the code span, and the sentence's own closing punctuation follows outside it.

Self-Audit Checklist

Before publishing, check punctuation against these questions:

• Do list items follow one consistent form (all sentences, all fragments, or all noun phrases)?
• Is the serial comma used in every list of three or more items?
• Is every semicolon either joining two closely related independent clauses or separating comma-containing list items — not standing in for a period?
• Does every colon follow a complete sentence?
• Are em dashes used without surrounding spaces, and sparingly?
• Are compound modifiers hyphenated before a noun and left open after one?
• Are UI element names bolded rather than quoted?
• Have all placeholder brackets been resolved before publishing?
• Are ellipses limited to reproducing exact UI states, not indicating vague or unfinished prose?
• Is "and" used in prose, with "&" reserved for exact UI labels or proper names?
• Are apostrophes used only for contractions and possessives, never for plurals?
• Does closing punctuation sit outside inline code spans, unless it's part of the code value itself?