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:
- 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:
- 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
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:
- 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:
