Knowledge Management Articles

Use this style guide to help standardize the content of your knowledge article. 

Sentence case 

"Clear the cache of the Google Chrome browser" 

All article headers should be in sentence case. 

Sentence case is when the first letter in the first word of a heading and any proper nouns are capitalized. 

Headings 

Logical heading structure helps readers understand the outline of a page’s content. Headings help readers find and keep their place, especially in longer articles.  

Headings are also important for people who use screen reader software to access text they cannot see. A common feature in most screen readers brings up a list of all headings on a page. The readers can then use that list to navigate through the page and drill down to the content they want to listen to. 

Best practices when using headings 

  • Use headings and subheadings to describe the content that follows in logical chunks. 
  • Headings should always be nested, consecutive, and formatted using heading levels <h2> through <h4>. When creating a new subheading, don’t skip heading levels. 
  • Avoid excessive nesting. For example, limit most content to heading levels <h2> through <h4>. 
  • You must use the Paragraph Format tool when creating headings. Do not use the font and font size tools independently to create a heading because then your headings will be imperceptible to people using screen reading software. 
  • Avoid heading-only content. 

Keywords, tags, and meta entries 

Keywords, tags, or meta entries should be entered as singular words or terms separated by commas. If a word appears in the title or body of an article, it does not need to be repeated as a keyword, tag, or meta entry. 

Abbreviations 

Abbreviations are acceptable if they are spelled out upon first use (e.g., escalate the incident to Customer Care Operations (CC Ops)). 

Boldface type 

Use bolding only for names of buttons and fields or for critical path items. For example: 

  • In File Explorer, go to:  
    • C:/readers/%username%/  
  • Click the Save to XML button. 

Italics and underlined text  

Avoid using italics or underlining words and phrases. Hyperlinks should be the only underlined text in knowledge articles.  

Quotations  

Quotation marks should only be used around words that people have said, or to denote that a particular text is being quoted.  

Dates and times  

Use the MM/DD/YYYY format (e.g., 10 June 1977 would be 06/10/1977).   

Use the HH:MM AM/PM Time Zone format (e.g., 3pm CST would be 03:00 PM US Central).  

Lists  

  • Use bullets for lists when order does not matter. Use numbered lists for procedural steps where order is important and there is more than one step.  
  • All lists, bulleted and numbered, should be structured as a list with the proper HTML tags. 
  • Use concise bullet points instead of long or compound sentences. 

Tables 

  • Don’t use a table when the same information can easily be presented in a list. Lists are more responsive to screen size and ratio changes. 
  • Include a title and a summary or table overview preceding the table. Screen readers use this information to describe the table for visually impaired readers. 
  • Ensure the header row or column and all header cells contain content. Empty header cells cause problems for readers relying upon a screen reader. 
  • Feature a single idea or piece of data per cell. Cells that contain a combination of different data types or ideas cause problems for readers relying upon a screen reader. 
  • Ensure cells do not span rows or columns. Merged cells cause problems for readers relying upon a screen reader. 
  • Whenever possible, define cell widths in percentages (%) and not as absolute pixel widths. This can help reduce issues when tables are displayed on smaller screens.
  • Avoid defining cell heights. Defining absolute cell heights can result in content being truncated when readers zoom in to make content larger. 

Input instructions  

  • Click, double-click, right-click: Use when referring to on-screen buttons (Click OK, right-click the Submit button).  
  • Choose: Use when picking an option from a menu or list. (Choose File from the dropdown.)  
  • Press: Refers to depressing a key on a physical keyboard. (Press Enter.)  
  • Select: Once something (a block of text, a cell in Excel) is selected, it stays selected. To undo this, it must be deselected.  
  • Tap: Use when referring to a touchscreen device such as an iPad. (Tap the Settings app.)  

File paths 

File paths should be in boldface type in a separate bulleted line to ensure accurate copying, for example: 

  1. In File Explorer
    • go to: C:/readers/%username%/  

Cautions  

Caution statements are warnings that appear in the body of articles and should be typed in red using capital letters (e.g., CAUTION: Rebooting the system at this time will result in loss of data.).  

Notes  

Notes are information that supplement a solution and should be typed in orange using capital letters (e.g., NOTE: Some Android devices and versions have different icons, labels, and paths than those described here.).  

Key combinations  

Use the plus sign (+) if keys must be pressed at the same time (e.g.,Press Ctrl+Alt+Del). Use commas for key sequences (e.g., Press Alt, F, then X).  

Numbers  

Use numerals (1, 52, 367) and commas for values above 1,000.  

Multimedia  

Hyperlinks  

Hyperlinks are typically used to refer readers to related articles in the knowledge base, documents, home pages, and external websites.  

  • Hyperlinks should always open new tabs. 
  • Because screen reader readers often choose to list the links on a web page, clearly and uniquely describe each link target.  
    • Describe the link destination instead of providing the actual web address. The letters, numbers, and symbols in a typical URL are not helpful for screen reader readers. 
    • Avoid vague phrases, such as Learn more or Go here, which give no context for people who access links from a list. 
    • Verify that there are no duplicate link labels on a page, unless you are intentionally sourcing link labels that refer to the same destination. 
  • If a link is going to an external domain, use an external link icon arrow pointing outside of a container  to indicate that to the readers and specify alt=“opens in new window”. 
  • For links that open in a new tab or window, let the reader know. One way to do this is to use link text such as: “XYZ link name [link opens in a new tab]”. 
  • URLS should be in a separate bulleted line, for example: 
    1. In a browser, navigate to: 

Videos  

Videos can be embedded in knowledge articles.  

  • Recommended size: Width – 480 px / Height – 360 px  
  • Avoid any animations that flash or blink more than 3 times per second. Otherwise, rapidly blinking animations can cause seizures in some readers. 
  • Any animations that last longer or repeat for longer than 5 seconds must include a way to pause or stop the animation 

Images  

Images should not exceed the size of the KB window (recommended size: Width – 480 px / Height – 360 px or smaller). Alterations to images should be made using an editing tool (e.g., SnagIt, Microsoft Paint). Acceptable graphic formats for knowledge base articles: .jpg, .jpeg, .png  

Alternative Text (Alt Text) 

  • Required for all images. 
  • Alt text should always be 100 characters or less. If you need more space, move some of the content to Descriptive text for the image. 
  • Should contain a brief description of the meaning or purpose of the image. 
  • Relevant information depends heavily on the image’s context. 
  • Write alt text and descriptive text when you write the content that surrounds the image. Alt text written after the initial content is drafted is usually less complete and effective. You might not remember why you included an image or details about that image. 

Descriptive text 

  • Required when the information that must be conveyed exceeds the recommended alt text limit. 
  • Provides a summary the image and describes the data provided in the image as it applies to the context surrounding it. 
  • If you include a chart or graph, the alt text summarizes the main theme of the data shown, and the descriptive text provides details about the data. To understand what information to convey about the image, think about why the image is being included. 
  • For more complex images, such as diagrams, charts, and infographic information, provide as much information as possible in the descriptive text surrounding the image, not in the alt text. Describe the information, properties of the information, and how different pieces of information relate to each other. Whenever possible, use a table or list to describe the data that the chart or infographic conveys. Then use the alt text to note that the image corresponds to the descriptive text, for example:  
  • alt=“Corresponding chart of information”. 
  • The combination of alt text and descriptive text must be an effective summary of the meaning of an image, so that nothing is lost for readers with impairments or readers who have turned off images. All readers must be able to get the same information from the alt text and surrounding text as if they could see the image. 

Attachments  

Acceptable formats for attachments include .jpg, .jpeg, .pdf, .png, and Office file types.  

Copying and pasting content from other sources 

Be sure to paste the content first into an application like Notepad, where any formatting is removed from the HTML source code, then paste it into the knowledge article. 

Additional training 

If you would like to learn more about the new Escalation Management Process, you can access our training at: 

Use these 12 helpful guidelines to ensure your article is easy to read and adheres to the document standards. 

Use the customer’s context

Capture enough information to make the issue distinct and usable. Record the issue or question in the customer’s words. This does not mean to capture bad grammar. It does mean to use the same keywords and phrases the customer uses. Use keywords that reflect the customers vocabulary (e.g., boards, KPS) and that are not already listed in the short description. 

Write with the audience in mind 

The solution must contain all the appropriate guidance required by the target audience. Be clear and concise. Use terminology carefully. Provide the appropriate level of direction. Write to the customer as if you were talking to them over the phone. 

Don’t create duplicates 

Search the knowledge base to ensure that your contribution will not be a duplicate. Duplicates create inconsistencies. If a consumer finds more than one article on a particular issue, how will they know which one is correct? If a duplicate exists, it may indicate that the original article needs to be modified to enhance findability. Adding the new context of the consumer is usually required. 

Don’t reference the agent, customer, staff member, or case 

Focus on the issue and the solution (e.g., Reset a Genesys password, not An customer wants to reset their Genesys password). 

Number the steps 

Numbered steps are easy to follow and imply that the order is important. 

Keep product names proper 

Consistency is created when all articles are associated with the same product name. Cloud is not the same as Genesys Cloud, WIN10 is not the same as Windows 10. 

Use reasonably sized graphics 

Large files can negatively affect response time. Screenshots should focus on the region of interest and not the entire screen. Images should not exceed the size of the KB window. The recommended image size is 480 x 360 pixels or smaller. 

Make attachments visible 

Ensure that attachments are located on an accessible file server, and that the file is a supported file type (see the style guide).

Avoid abbreviations and acronyms 

Acronyms should only be used if they are defined on the first usage within an article or the acronym is a brand or is common to the audience. 

Always check spelling 

Many common spelling errors can be eliminated by using a spellchecker. 

Follow the style guide 

Articles should adhere to the standards detailed in the style guide. This ensures consistency, making articles easier to follow. 

Use correct hyperlinks 

Hyperlinks should point users to the intended URLs or documents and should open in a new tab. Links should not be dead or broken. 

Announcements

Case Escalation Management Process

This article outlines the process for escalating an open case with customer care, including the criteria a case must meet in order to be escalated, how to submit an Escalation Request through the My Support Portal, and the Escalation Management Process that Customer Care follows once an Escalation Request has been submitted.

Escalation criteria

Note: If a case requires engagement of Development, Cloud Operations or a 3rd party, please understand that it may require additional time to resolve, pending their analysis and findings.

  • There must be an active case for the Escalation
    • Closed Cases: If your case is already closed, the Escalate Case button will not be active. If you need to reopen a case, please do so through the MySupport portal or call into our Care team to request a case reopen.
    • No Case: There must be an existing case open with Genesys Product Support team before it can be escalated.
  • Double-check your case before requesting an Escalation
    • Has there been a recent update to the case that you may have missed?
    • Is Genesys Product Support waiting on additional information from you before they can proceed?
  • Is there already an active Escalation on the case? While multiple escalations can exist on a case, only one can be active at any given moment. If there is an open Escalation on your case already, you will not be able to submit a second until the first is closed.
  • Please do not request an Escalation based on change in urgency/impact. If a case needs to be changed to a higher priority based on a greater need for urgency or broader impact, please call in the request to our care team
  • An Escalation should not be requested for a Root Cause Analysis (RCA) unless Genesys Product Support has had 5 business days for cloud deployments or 7 business days for premise to complete analysis, per our standard Service Level Targets for RCA delivery (listed in your Customer Handbook: – PureConnect Direct Customer, PureConnect Partner Handbook, PureCloud).
  • If a high priority case has not been updated in the last 24 hours and the case is actively causing significant business impact, an Escalation can be requested.
  • Low priority cases are not eligible for escalation, if the impact of a low priority case changes, please request a change to medium through a work note in the case. If a change to high is required, please contact our care team by phone.

How to submit an Escalation Request

  1. From the MySupport portal, select the case you wish to escalate
  2. Navigate to the bottom right-hand corner of the case page and select Escalate Case. (If the Escalate button is disabled, it is most likely due to an already existing and open Escalation. See Escalation Criteria section for more info on multiple Escalations..)

    Screenshot of a case record in the My Support Portal. Escalate Case button is highlighted.
     
  3. A new window will open, displaying the Escalate Case form. There are two main fields:
    • Reason: Select the reason for the Escalation. Once a reason is selected, you may be prompted for additional information.
    • Escalation Details: This may include any initial notes which the Escalation Owner may need.
  4. Once the form is completed, click Escalate Case.
  5. Once the case has been escalated, a time stamp will appear within the case, and a banner will pop-up across your screen, confirming the Escalation has been created.

Escalation management process

  1. Customer or Partner submits an Escalation Request. 
  2. Escalation Owner reviews request and determines if it meets the Escalation Criteria
  3. Escalation Owner replies to request with next steps. If the Escalation Request is invalid, the Escalation Owner will provide reasons why and provide process information to the requestor.
  4. If Escalation request is valid, the Escalation Owner assesses the situation, prioritizes the Escalation by importance and urgency, and works with the engineer(s) to set expectations regarding next steps.
  5. Escalation Owner updates the case with all additional external communications with the customer or partner, regarding the Escalation.

Communicate directly with Escalation Owner

You can communicate directly with the Owner of the Escalation from the Escalation Feed section on the case. There will now be two feed sections on the case. 

  • The Case Feed will capture the technical aspects of the case. 
  • The Escalation Feed will capture the communication flow of the Case Escalation.

Please be mindful of the type of update you are sending and use the appropriate feed section for your update.

Additional training

If you would like to learn more about the new Escalation Management Process, you can access our training here: https://rise.articulate.com/share/0N9zbnlzRL2HDa9AGu9rm1Yw5BOZnBNI using the password: Genesys2022.

Overview of the My Support Portal

Only Designated Contacts have access to create, update, close, or re-open a case. Other employees who work for Genesys direct customers, Partners, Resellers, or end users can request Read-Only access to the My Support Portal to view cases opened by Designated Contacts on behalf of their company.

The My Support Portal allows you to:

  • Open and manage your support cases (Designated Contacts only)
  • Search our Knowledge Base and Technical Documentation site
  • Register for and view our Genesys Engage Tech Tutorials
  • Learn about current Product Support news and announcements
  • Access Genesys Care Apps and Tools (Designated Contacts only)