Punctuation

Use punctuation consistently to support clarity in technical and instructional content. Prioritize readability and precision, and avoid stylistic punctuation that introduces ambiguity, informality, or tone that does not translate well globally.

Periods

Use periods to mark complete sentences.

Use a single space between sentences.

In bulleted or numbered lists:

• Use a period if the item is a complete sentence or continues the sentence that introduces the list.
• Do not use a period if the item is a single word or short phrase.
• All items in a list should follow the same punctuation style.

Commas

Use serial commas in lists. For example, “Our products include object storage, block storage, and load balancers.”

Colons

Use colons to introduce lists, examples, options, steps, or clarifications. For example, “The CLI accepts the following flags:”

Semicolons

Use semicolons rarely. Only use a semicolon to connect two closely related independent clauses that could stand as separate sentences but read more clearly when linked. For example, “The service restarted; the issue resolved itself shortly after.”

Avoid semicolons in lists or as a stylistic substitute for commas or periods.

Quotation Marks

Use quotation marks consistently based on context.

Use straight quotes (" " and ' ') in:

• Code blocks
• Configuration files
• JSON
• Commands and command-line examples

Use curly quotes in narrative text. For example, “This is the correct formatting.”

Use single quotes for nested quotations within a quoted sentence. For example, “Select the option labeled ‘Advanced settings.’”

Parentheses

Limit the use of parentheses to brief clarifications, flags, parameters, or optional details. For example, “Run the script with the --verbose flag (optional).”

Avoid stacking or overusing parentheses. If a sentence becomes dense or nested, rewrite it for clarity instead.

Hyphens and Dashes

Use hyphens only where required, such as for compound adjectives, ranges, or technical notation.

Use a hyphen (-) for compound modifiers and ranges.

Do not use en dashes (–) or em dashes (—).

Do not add spaces around hyphens used in ranges.

For detailed hyphenation rules and examples, see the Hyphens style guide.

Exclamation Marks

Use exclamation marks sparingly. They convey emotion, urgency, or enthusiasm, which can sound informal or unprofessional in technical documentation.

Avoid exclamation marks in reference material, procedural steps, error messages, warnings, API documentation, and other instructional or technical content. They can introduce a tone that feels emotional rather than precise.

Do not use exclamation marks to dramatize errors, failures, or security-related messages.

If emphasis is necessary, rewrite the sentence for clarity instead of relying on punctuation for tone.

Use exclamation marks only when appropriate for non-technical, expressive content, such as marketing materials, blog posts, congratulatory messages, or announcements intended to sound encouraging or celebratory (for example, announcing a product launch or milestone).

Ellipses

Use ellipses only in specific technical contexts:

• To represent truncated output in UI or terminal examples.
• To indicate omitted text in quoted material.

Do not use ellipses to convey tone, suspense, or informality.