Leading practices

Draft an article and note any questions that you have along the way. Once you’ve written your first draft, try to answer your questions using internal resources (for example, search Coveo@Coveo). If you get need assistance, ask the developer assigned to the maintenance of the project to which the article is related (see the Maintenance Calendar).

Self-review your draft before submitting it for peer review.

Once you’ve finished writing an article, send it to a subject-matter expert for review if necessary.

On new features and release note pages, always place the newest content at the top.

Favour the simple present tense (for example, favour Click the button, and then close the window over Once you’ve clicked the button, close the window).

Favour the active voice (for example, favour This component does awesome things over Awesome things are done by this component).

In product documentation, use a neutral tone.

In tutorials, use a somewhat more conversational tone.

Our reference dictionary of choice is Merriam-Webster.

Use the terms article, page, or tutorial, but avoid using the word topic when referring to a single document.

In normal articles on docs.coveo.com (as opposed to Swagger, the Search UI GitHub, etc.), we use contractions to make our writing friendlier and more approachable. We currently allow the following contractions:

In tutorials on docs.coveo.com, we use an even more casual tone. We allow contractions that aren’t allowed elsewhere in the docs (for example, you’ll, you’ve, we’ve and aren’t).

It’s best to focus on what users should do, instead of what they shouldn’t do. Instead of using do not or don’t, try to rephrase the sentence with positive language. If you have to use don’t within a sentence, that’s okay, just look for other options. You must avoid writing DO NOT or don’t in all caps, all italics or in bold.

Avoid using idiomatic language (for example, a blessing in disguise, cutting corners, and on the ball).

Avoid using transitive verbs (for example, find out, give up, and give in). The only exceptions are log in, log out, sign in, and sign out.

Data and metadata are singular uncountable nouns. You can’t use a data/metadata, nor can you use datas/metadatas. When you need to refer to a single piece of information, append a singular countable noun (for example, piece of data). When you need to refer to multiple separate pieces of information in the aggregate, append a plural countable noun (for example, metadata values).

E.g. is a Latin abbreviation which means "for example". It’s used to introduce one or more examples of something that was mentioned previously in the sentence. Don’t confuse it with i.e.. You can’t begin a sentence with e.g..

I.e. is a Latin abbreviation which means "that is". It’s used to introduce a rewording or clarification of something that was mentioned previously in the sentence. Don’t confuse it with e.g.. You can’t begin a sentence with i.e..

End user and end users are nouns, while end-user is an adjective.

Use checkbox and checkboxes, not check box and check boxes.

Use phrases like Coveo-powered solutions, Coveo-powered search interfaces, Coveo-powered applications, and Coveo-powered search pages. Don’t refer to the products directly (for example, Coveo Cloud) or use other formulations (for example, Coveo Cloud powered).

When making suggestions, use the first person plural subject (that is, we recommend that). Don’t attribute suggestions to Coveo by name (that is, Coveo recommends that). Don’t use a third person subject or make a recommendation in the passive voice (for example, it’s recommended that or …​ is recommended).