Article format

Content basics

Articles assume very little knowledge of other articles and provide plenty of links.

Reuse existing content or link to it instead of duplicating it. Our new content-reuse strategy will eventually give us a single source of truth.

Articles should never have overlapping content. When things change (and they always change), you only have to update the related documentation in one place.

Titles and headings

Article titles are h1. The Docs site supports heading levels up to h6, but avoid using headings below h4.

Note

The TOC on the right side doesn’t show headings below h4.

Keep titles and headings short, precise, and complete to optimize findability.

Adding too much information will have a negative impact on the Table of Contents (ToC), but having too little information won’t provide an optimal search experience. You’ll need to find the perfect balance.

Example

How to Properly Index Website Content → Indexing Website Content

Our site search is based on heading text, so headings should be as descriptive and unique as possible, without being so long that they make the TOC on the right side hard to read.

Example

Toggling a Facet Value from a Result List Item

Capitalization

Titles and headings should always be in title case.

You can convert your text to title case at https://capitalizemytitle.com/, using the Default option.

If your title or heading includes a component or parameter name that begins with a lowercase letter, do not convert the name to title case.

Special elements and names

When a UI element is contained in a heading (except for h1), make sure to put the element between double quotes.

Example

Accessing the "Sources" Page

When a component or parameter name is contained in a heading (except for h1), make sure to put the name between backticks.

Example

constantExpression Queries

Procedures

Titles or headings should begin with the appropriate gerund verb.

Example

Implementing Facets

Include the object of the action, with enough details to distinguish this article or section from similar ones.

Example

Implementing Facets Using GroupBy Operations

Special capitalization rules

Reproduce capitalization of Coveo and third-party company products and feature names when referring to them (see our Naming Conventions).

Example

Coveo Administration Console

Exception: for Coveo UI elements that are in ALL CAPS (applied automatically with CSS), use title case instead. This is because the UX team could change the design and eliminate the use of this casing.

Example

ADD SOURCE → Add Source

Introductions

Articles should begin with an introduction that answers the basic content questions (who, what, where, when, how, and why).

Consider adding a schema or figure to help explain complex or important concepts.

Include a capture of the result (for procedures) or example (for concepts).

Include any notes, important mentions/warnings, or tips that are applicable to the whole article.

If applicable, include a Prerequisites or Requirements section.

Prerequisites and requirements

Prerequisites are actions you must take before you perform a procedure.

Requirements are the necessary hardware and software.

Troubleshooting articles

Troubleshooting articles consist of the following sections:

Symptoms

  • Describe the symptoms, and include the error message and where it appears.

Causes

  • List the probable causes or some of them (most frequent).

Resolution

  • Explain the steps or actions to fix or work around the issue.

Fix ETA

  • If this is a known issue, include (when possible) the estimated time until a fix is available.

Glossary entry articles

Use full product and technology names in glossary entry descriptions.

Example

Coveo Usage Analytics, instead of Coveo Usage Analytics (Coveo UA) or Coveo UA.