Procedures

Answer the How? and Where? questions with an ordered list.

Stem sentences

When there is an introduction containing more than one paragraph, add a stem sentence to mark the beginning and purpose in bold. Don’t add end punctuation and use sentence case (for example, To configure something).

  • Only use when the article describes how to perform a single action.

  • Place the stem sentence in a paragraph element (that is, <p>) and apply a class attribute instead of a heading attribute (for example, <p class='stemSentence'></p>).

Prerequisites and requirements

If there is only one prerequisite or requirement, use the following format for the first step: "Ensure that you <did the following action>." If there are multiple prerequisites or requirements, create a dedicated section instead.

  • Prerequisites refer to actions that must be taken before performing a procedure.

  • Requirements refer to hardware and software.

In steps with sub-steps, introduce what the user will do and end the sentence with a colon (:).

Example

In the Update Access Token panel, retrieve another access token:

When the location is accessible through a single method (for example, all Coveo Administration Console pages), start the step with a direct link to the page (for example, On the Named Filters (platform-ca | platform-eu | platform-au) page).

  • No step to access the page.

  • No (see [Access the page]) links.

  • Ensure that there is a section topping the article on how to access the page via the UI.

When you can access the panel or dialog in different ways, add a step with an inline link to the Access section of the article (for example, [Access the "Activity" panel](#access-the-activity-panel)).

When the panel or dialog is related to the prior selection of a resource (for example, panels in Coveo Administration Console pages), name the panel name, but don’t provide access links or steps to access the panel (for example, In the Add extensions panel,).

  • No step to access the panel or dialog.

  • No (see [Access the panel]) links.

  • Ensure that there is a section topping the article on how to access the panel or dialog via the UI.

  • On the page/subpage, but in the dialog, tab, panel, input, etc.

When describing locations as places/objects to navigate to on a page, avoid listing multiple locations with commas. Instead, start the step with the location of the page element, add the action, and then, if applicable, finish with the location direction requiring you to guide the eye.

Example

In the <PAGE ELEMENT>, in the menu on the upper right side of the page, click <BUTTON>. →
In the <PAGE ELEMENT>, click <BUTTON> in the menu on the upper right side of the page.