Skip to main content

Writing guidance

Primary guidelines​

  • Clearpath usage guidelines
  • Clearpath writing guidance

Quick reference​

Formatting​

GuidelineWrongRight
Bold names of elements visible on a screen, like interface elements (headings, buttons, links), table components, errors, etc.Click Save.Click Save.
Use plain text for nouns.Open the SAM...Open the SAM...
Italicize terms when defined.In this guide, Securable type refers to...In this guide, Securable type refers to...
Use the code character style (backticks in Markdown) to display what a user types in or API methods.
  • Press Enter.
  • Send a GET request.
  • Press Enter.
  • Send a GET request.

Style​

Word choice​

GuidelineWrongRight
If it can be said in fewer words, take the opportunity....before taking the timeout action......before timing out...
...completed its loading process......finished loading...
...in situations where......when...
...warrant failure of......fail...

Usage​

GuidelineWrongRight
Use active voice....when source marts are loaded......when source marts load...
Use present tense.
  • ...the application will save the files...
  • ...the application should save the files...
  • ...the application saved the files...
...the application saves the files...
Use second person....the files need to be re-uploaded......re-upload the files...
...allows for the selection of......lets you select...
Standardize singular vs. plural (singular is preferred).To import files, load the file from the database.Load a file to import it from the database.
Lowercase improper nouns.Source Martsource mart
...save the Record to the Database......save the record to the database...
Click, don't select, buttons.Select the OK button.Click OK.

Headings​

GuidelineWrongRight
Make article titles and headings imperative; avoid gerunds (-ing).Designing a source martDesign a source mart
Make headings sentence case.Build an ApplicationBuild an application
Capitalize only the first word of a heading unless it has proper nouns.Create a Forge ApplicationCreate a Forge application

Bullets and numbers​

  • Use bullets, not numbers. Often authors exploit numbered lists by creating deeply nested outlines.
  • Punctuation:
    • If the list items are complete sentences, end them with periods.
    • If the list items are not complete sentences, don't add periods.
  • Break up long bulleted lists into multiple sections with headings.

Screenshots​

  • Put the screenshot before the step.