Knowledge Article Style Guidelines

Overview

It’s important Knowledge Base (KB) articles contain the information that customers are looking for, using common language they are using for search terms/tags, and formatted for ease of use, and accessibility. When writing knowledge articles maintaining consistency between one article and the next with regards to formatting, color choices, font styles, etc. is important. Having a standardized style for all articles makes it easier for customers to navigate because they’re already familiar the layout of information. The UAA Service Portal has adopted a style that follows UAA's existing branding, image standards, fonts and colors as appropriate.

In this article:

• General Best Practices
• Templates
• Keywords
• Images
• Font Styles & Formats
• Grammar and Spelling
• Hyperlinks
• Attachments
• Keyboard Controls
• UAA Style Guide

General Best Practices

• Use a template: The templates are built so that the correct font, font size, spacing, headings, and color scheme have already been preset.
• Articles should be brief to consume information in complete, yet concise chunks. Articles do not need to be long or complex to be good.
• Keep the instructions simple. One step should cover one point. Separating instructions into clear points makes it easier for the customer to follow along.
• Articles should use language and terms familiar to customers for public facing articles. This assists in searches and meeting the customer at their support level first. Example: use "computer" instead of "machine."

Templates

Templates help you create articles quickly and ensure key web accessibility features are included. Templates for different article types are available under the Templates drop-down menu. When creating a new article choosing the correct template helps speed up KB authoring, and with with practice makes authoring more efficient. Additional information on the use and details of templates is available within the Knowledge Article Templates article.

Keywords

Keywords should include product, or service names, key concepts, error codes, synonyms, and acronyms. Additional information can be found in the Enterprise Service Management Tags article.

Images

Use images in your article to make it easier to follow along and understand—but only when they add value. Screenshots can be helpful for visual learners or to clarify a complex step; however, if the image is too big, small, or not aligned properly it will not effectively assist in helping the reader. Images should never replace written instructions.

The following are guidelines to keep in mind when using images:

• Always include a short description (also called alt text) for each image. This helps people using screen readers understand what the image shows.
  • Keep it simple — just explain what what the primary focus area of the image is (e.g., "Login button in the top-right corner").
• Avoid adding text directly on images whenever possible. Screen readers can't read it, and it often becomes blurry on mobile devices.
• Don’t rely on images alone to explain something. Always include the steps or information in text, even if you're also showing it with a screenshot.
• Images should support your content, not replace it.
• Make sure you image is sized to load quickly on mobile devices and show up correctly on varied screen sizes. 
• Maximum image width of 700 pixels (px). Any image larger than this should be scaled down in an image editor before being uploaded to TDX.
  • Any animated GIFs must not exceed the 700 px requirement otherwise when TDX resizes the image it resaves it, and removes all animations.
• Minimum image Dots Per Inch (DPI) of 144 dpi. Large screen shots (e.g. dimensions of 10” or greater) can be scaled down to 700 pixels width, and have the DPI increased (usually from a default of 72dpi) at the same time.
• Be cautious of very small images, especially containing text, as they can be difficult to read.
• Highlight areas on a screenshot when appropriate. Use a dark washed red color (RGB value: 216, 0, 65 Hex: #CC0000).

Read the Create Effective Images article for additional information

Font Styles & Formats

• Section headers: Make sure section headers use the appropriate level or format. They should always be in a numerical order, do not place a 3 after a 1. Although headers are used for formatting the text they are also used by screen readers for identifying content sections.
  • Use headings to break up content into easily digestible chunks. If one article requires the customer to complete two different sets of actions, it’s a good idea to stick them underneath separate headings.
• Bold text: The bold style should be used, typically in “how-to” articles, when telling a person what to action to do (e.g. Click, double-click, etc).
• Italic text: The italic style should be used, typically in “how-to” articles, when referencing/describing what is seen on the screen (e.g. Image Properties dialog window, Finder icon).
• Underline text: The underline style should be avoided as it is most commonly used to identify hyperlinks. Hyperlinks will automatically be given the appropriate formatting when created using the link action.
• Numbered Lists: Use numbered list formatting for step-by-step directions. The initial numbering scheme should be numeric (e.g. 1, 2, 3). Second level type should be alphabetic (e.g. a, b, c), with third level type roman (e.g. i, ii, iii, iv, v).
• Bulleted Lists: Use bulleted list formatting for a list of related items. The initial bullet type should be circle. Second level type should be disc, with the third level type being square.

Grammar and Spelling

Make sure to proofread documents after they are completed, before submitting them for review. Accurate spelling and grammar communicate attention to detail and good understanding of the concepts.

Hyperlinks

When writing articles make sure that all links function. When reviewing articles make sure to verify that every single link in the article works. When creating links the link's text should describe where the link goes (e.g. Contact UAA IT Services Support).

Attachments

If you need to include additional documentation such as spreadsheets, word documents, or PDF files, make sure they are accessible. You can link them to the KB article and reference them by replacing the placeholder text <FILE> and <summary description> as appropriate.

Keyboard Controls

Capitalize the titles of keys on the keyboard. Keys that should be pressed at the same time should be typed with a + sign.

Examples:

• Press CTRL + ALT + DELETE to login.
• Press CMD + S to save the file.

UAA Style Guide

UAA has a well-documented style guide when writing any kind of documentation we should always keep these in mind:

• Our Brand
• The Official UAA Brand Book
• Image Standards & Logos
• Colors & Fonts