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

How do I create a My Support account?
  1. Navigate to: 
  2. Click the GET STARTED tab. 
  3. Click the Request My Support Account button. 
  4. You will be asked to supply your corporate email address. 
  5. You will be asked to specify which level of access you are requesting.
  6. There are three levels of access:
    • Basic
    • Read-Only
    • Read-Write (Designated Contact)
  7. If you are not certain which level of access is appropriate for your role, see My Support Access Levels.
What are the levels of access for the Support Portal?

My Support functions for each level of access

Levels of access are listed below from least amount of access to most. In each subsequent level after Basic, new access permissions are in bold type.

Basic

  • Log into My Support Portal
  • Register and attend live Tech Tutorials
  • View and download recorded Tech Tutorials
  • Search, view and download Knowledge Base content

Read-Only

  • Log into My Support Portal
  • Register and attend live Tech Tutorials
  • View and download recorded Tech Tutorials
  • Search, view and download Knowledge Base content
  • View existing Cases

Read-Write (Designated Contact)

  • Log into My Support Portal
  • Register and attend live Tech Tutorials
  • View and download recorded Tech Tutorials
  • Search, view and download Knowledge Base content
  • View existing Cases
  • Create new Cases, modify existing Cases, submit Feature Requests
  • Download software and order controlled software

Request an account

If you do not currently have an account on the My Support Portal, see Create a My Support Account for instructions on how to request one.

Request a different level of access

NOTE: If you are a member of an organization that has purchased Genesys products from one of our Genesys Partners, then your Designated Contact is a member of that Partner organization. However, you can still request Read-Only access using the process below. For more information on this, see: How a Genesys Partner Serves as Designated Contact for Their Customers.

  1. Login to the Support Portal. You will automatically be directed to the My Support Cases page.
  2. Click on your name in the upper right-hand corner of the page.
    • A screenshot of the Support Portal with a large orange arrow pointing to the words, "Welcome back, Matt Ryan."
  3. Click My Support Access from the drop-down menu.
  4. Complete the Request Additional Access form.
    • NOTE: If you are a member of a Genesys Partner organization and you are requesting Designated Contact status for one of your customers, in the Company/Partner Combinations (End User/Sold To) box, enter your Company name, the names of the companies/accounts you manage (if applicable), and corresponding Org IDs. If you need help locating an Org ID, go here. The Portal Admin team will seek approval from your company’s Designated Approver(s). Once approved, you will receive an email from donotreply@genesys.com with instructions.
  5. Click Submit Request.
  6. Please allow 48 hours or 2 business days for Product Support to process the request.
  7. A Product Support Admin may contact you by phone or email to obtain additional information.