Punctuation

Punctuation is essential as it provides the reader an accurate understanding of the text. It’s required in every written sentence and helps articulate ideas properly. However, an excessive use of punctuation within a single sentence will render it more complex than necessary. Therefore, we recommend avoiding run-on sentences and keeping your text clear and concise.

Periods

  • End all sentences with a period and then follow the end of the sentence with a space.

  • When writing a bulleted list:

    • If one or more list elements are more than three words and complete the list’s introductory phrase, use a period after every list element.

    • If a bulleted list has no introductory phrase and one or more list elements are complete sentences, use a period after every element, regardless of the number of words in each element.

  • Headings, subheadings, UI titles, and UI text don’t require a period.

Commas

  • Use a comma:

    • Before the conjunction in a list of three or more items.

      Example

      This article contains names of brands, products, features, and services.

    • Following an introductory phrase in a sentence.

    • To join independent clauses with a conjunction, such as and, or, but, or so.

      Example

      Click Filter, and then select the organization in which you want to create the API project.

    • To surround the year when you use a complete date within a sentence.

      Example

      Construction began on April 9, 2019, and lasted two years.

  • Don’t use a comma to surround the year in a What’s New announcement.

    Example

    You can now review the content and related documentation of the Coveo Platform June 16, 2021 release.

For information about using commas in numbers, see Numbers.

Apostrophes

Don’t use an apostrophe for the possessive form of trademark, product, service, or feature names.

Example

Coveo Administration Console Visit browser

Colons

  • Use a colon at the end of a phrase that directly introduces a bulleted list.

  • Avoid using a colon within a sentence to expand on a statement. Instead, create two separate sentences.

  • When you use a colon in a title or a heading, capitalize the word that follows it.

Semicolons

  • Don’t use semicolons between independent clauses, contrasting statements, and items in a list. Instead, create multiple sentences for clarity.

En dashes

  • Use an en dash:

    • To indicate a range of numbers, such as inclusive values, dates, or pages.

    • For a minus sign.

Hyphens

  • Use hyphens for compound nouns when one of the words is abbreviated (except for the word email).

    Examples

    • E-transfer

    • E-bike

  • Avoid using hyphens to create new words by adding prefixes, unless it’s to avoid confusion.

    Example

    Non-fungible

Slashes

  • Don’t use slashes as a replacement for a preposition, unless referring to a UI element that has more than one functionality.

    Example

    Open the Add/Edit a Web Source panel.

Parentheses and brackets

  • Use the same font style for the closing parenthesis or bracket that you use for the opening parenthesis or bracket.

  • Format parentheses and brackets in the font style of the main text, not of the text in the parentheses or brackets.

    Example

    The geographical ID (geoid=US) is a two-letter country code or a criteria ID.

    In this example, the opening and closing parentheses aren’t in code, to match the main text.

  • Use angle brackets when writing a variable value in a code sample.

    Example
    searchHub: "<MY_SEARCH_HUB>"

Formatting

  • Format punctuation in the same font style as the main content of a sentence or phrase.

  • When documenting UI elements:

    • If the punctuation is part of the UI element, format the punctuation the same as the element.

      Example

      In the list of dimensions, select Origin 1 (Page/Hub).

    • If the punctuation isn’t part of the element, format the punctuation the same as the main text.

Quotation marks

  • Use single quotation marks when writing user input.

  • Use double quotation marks when writing an attribute value in a code sample.