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: