Formatting

Basics

• Keep paragraphs to 4 lines or less, when possible.  
• Use bullet points to list features or additional points.  
• Left-align images in online help and in most printed documentation. You may wrap text around images as a style choice in printed documentation.  
• Use bold font to emphasize important words or content (see below). Do not use bolding or italicizing for portal/product names.
• Be attentive to the document's overall design. Take into account elements such as organization, consistency, readability, and visual appeal by utilizing headings, lists, spacing, white space, etc.
• When referencing other pieces of documentation or resources, follow these formats:
  • In CXone Expert, hyperlink the article name (e.g., For more information, see the WebAdMIT Help Center).
  • In Schoox and easygenerator, hyperlink the resource, if possible. Otherwise, use bolding.

Bolding

• Use to set apart UI element names (e.g., “Organization drop-down”), references to row and column names in tables, page names, section names, report names, etc.  
• Use to set apart an item in a list that is followed by a colon (e.g., “Citizenship: select US, Visa…”). 
• Use to emphasize important words or content, sparingly.  
• Do not use red bold font for emphasis. Reasons include:
  • Research shows it doesn’t make a significant difference.
  • Red text can be problematic for users with visual impairments, particularly those who have color vision deficiencies.
  • When frequently used, it creates visual noise and becomes overwhelming (they may start ignoring it or become desensitized to it).
  • Red doesn’t align with the overall color scheme and is visually inconsistent.
  • Red text has a negative subconscious connotation (e.g., graded tests and assignments in school).
• Use for headers if another style does not apply.

Italics

• Use for references to sections in eLearning courses. 
• Use for table or graph names.
• Use for image descriptions. 
• Use for emphasis, sparingly.  

Lists

• Ensure all lists in a document are consistent.
• Ensure lists follow parallelism.
• Use numbered lists when documenting steps or an order of operations.  
• Avoid widows/orphans.  
• Avoid using lists for a single item.
• Ultimately, you can decide whether to use periods; just be consistent throughout document. Some ideas: 
  • Use periods for complete sentences in a list or lists that finish the preceding clause. 
  • Do not use periods for lists with simple nouns/ideas.

Hyphens, En Dashes, and Em Dashes

• Use hyphens (-) for adjectives, nouns, etc. (e.g., call-out).
• Use en dashes (–) for date and number ranges (e.g., August–May).
• Use em dashes (—) to separate a clause from the rest of the sentence with no spaces before or after the dash (e.g., The dog—and I rarely pet dogs—was very cute). Alternatively, you can use an en dash and add spaces before and after the dash (e.g., The dog – and I rarely pet dogs – was very cute. Within the document, stay consistent.
  • Shortcuts for Macs:
    • en dash: Option + Dash
    • em dash: Option + Shift + Dash

Other Formatting Specifications

See CXone Expert Style Specifications for more information when formatting in Expert.