Knowledge Article Style Guidelines

Overview

It’s important that knowledge articles contain the information that customers are looking for, but is also formatted in a way that makes the answer clear and obvious. Having a standardized template for articles makes it easier for customers to navigate because they’re already familiar the layout of information. Accordingly UAA IT Services has adopted the following KB template.

Articles are typically classified as either:

• Informative/About: These articles typically cover general information on a specific subject (e.g. Getting Started with Service Name), and do not cover specific troubleshooting steps, or provide instructions on how to perform a specific task. However, it is acceptable, and appropriate to create links to related how-to articles from these informative articles.
• How-to: These articles are typically brief. They show you exactly what steps to take to complete a specific task, or perform a certain function. Complex topics should be broken down in to multiple articles, with each one covering a specific topic (e.g. How to login to Microsoft Forms), with links to the next topic in the sequence (e.g. Creating your first Microsoft Form). Instead of trying to cram everything into one overly complex, and extremely long, article. Breaking up complex topics into smaller, easier to digest chunks makes it easier for customers to be successful.
• Policy: This template is used to help ensure consistency between policies and to increase clarity. If reproducing University of Alaska Board of Regents (BOR) policies within the the knowledge base maintain the headers, and sub-headers within the source document.

Accordingly, we have create templates for each of these article types which are available under the Templates drop-down menu. When creating a new article, after clicking the New Article button, always select the appropriate template before you begin writing.

In this article:

• Knowledge Article Sections
• Knowledge Article Style Guide

Knowledge Article Sections

The various article templates have different sections headers specific to content they are designed for. The following covers the "how-to" template as it illustrates the sections used and the styling applied. These are comparable to the sections available within the other templates.

Title / Subject

Effective knowledge article titles should be simple, clear, and concise. Most importantly it needs to be customer focused! If the customer doesn't know that the knowledge article can solve their problem, it doesn't matter one bit how good it is. Use simple English, avoiding jargon and abbreviations whenever possible. Within TDX the Subject field becomes the articles title and will be formatted with a H1 html style. No other article section should be formatted with the H1 style.

Getting the title right is vital for search, most of the traffic to an article comes from a search, either from the site search, or an Internet search engine such as Google, or Bing. The title should be a short description of the article's main theme. Capitalize the first, last, and any important words in a title, this is known as Title Case. Generally, we do not capitalize the following: a, an, the, and, or, for, but, etc.

Examples:

• Change my UA Password
• Top 10 Technology Tips for UAA Students
• Knowledge Article Style Guidelines

Overview

A succinct description regarding the purpose of the article. Typically this is anywhere from a few sentences to a paragraph or two. This lets readers know they’re in the right place for their question, and properly sets their expectations for what they’ll be reading.

For specific topics, be specific. For example, if the article is about solving an error message, discuss the error message in the first paragraph. Quickly explain why the customer is receiving the error message before jumping into solving it.

What materials do I need

A list of elements required to complete the task such as required hardware, software, etc.

Examples:

• A computer running Windows 10, or later
• Microsoft Edge, or Mozilla Firefox web browser

How do I use this technology?

If you’re familiar with the technology, writing instructions can be surprisingly difficult. You know the ins and outs, so it’s easy to forget that the customer may lack the same level of expertise. Don’t do that.

Keep the instructions simple. One step should cover one point. Separating instructions into clear points makes it easier for the customer to follow along.

Use intelligent 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. The section header will be formatted with a H2 html style, subheadings created within in this section must be formatted using H3, H4, H5, or H6 tags in ascending order.

Write in a logical order. Instructions should be written in the order in which a person will go through them. Each step should be one step, do not combine multiple.

Example:

Do:

1. Click the File menu.
2. Click Open.

Do not:

1. Click Open on the File menu.

Next Steps

If you’re breaking up a long and complex article into multiple shorter articles include a Next Steps section with links to the next article(s) in the series progression.

• Example link to the next step in the series
• Example link to a divergent step in the series

Attached Documentation

If you need to include additional documentation such as spreadsheets, word documents, or PDF files, make sure they are accessible. Link them to the KB article and reference them in the main body of the article as follows, replacing the placeholder text <FILE> and <summary description> as appropriate.

Please see the attached <FILE> (in the Files section of this article) for <summary description>.

Is there any additional information I should know about?

Good knowledge bases don’t just solve the current problem a customer is facing, they also solve the next problem before the customer even knows they need help. You can achieve this by linking KB articles together. This encourages customers to learn even more about the topic they’re researching.

Need additional help or have issues

For additional assistance contact the IT Services Technical Support Center via phone at (907) 786-4646, toll-free at (877) 633-3888, email us at uaa.techsupport@alaska.edu, or visit the Services section to open a support ticket.

Knowledge Article Style Guide

When writing knowledge articles maintain 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.

Keywords

Keywords should include product, or service names, key concepts, error codes, synonyms, and acronyms. 

Images

Images often make conveying instructions easier to read and understand. However, if the image is too big, small, or not aligned properly it will not effectively assist in helping the reader.

The following are guidelines to keep in mind:

• 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.
• Add a border using image properties, this will make it easier to identify text between images.
• Highlight areas on a screenshot when appropriate. Use a dark washed red color (RGB value: 216, 0, 65 Hex: #CC0000).
• Do not include any images which contain text directions, unless the directions are also included in the article. Screen readers can not read text on an image.
• Always include Alt Text that clearly describes what the image is demonstrating (e.g. Microsoft Teams preferences dialog window screenshot).

Read the Create Effective Image 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.
• 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.

Call Outs

When the need arises to emphasis specific text, usually notes, or asides, place them in formatted text boxes. When you do add such information make sure to use the Call Out templates to it is formatted appropriately. The templates include the below style.

Tables

Properly using tables ensures that individuals relaying on assistive technologies, such as screen readers, can effectively access and understand the content being displayed.

When using tables within knowledge articles ensure they align with the following requirements:

• Tables should only be used to display data in a grid. Do not use them as a means for content layout. As a general rule, tables are not meant to be used for layout purposes.
• Header: Every table must have at least one header. Either a header row, header column, or both.
• Caption: A caption identifies the overall topic of a table and is useful in many situations.

Tables should use the built in table styles it is recommended to add in additional formatting properties for easier reading such as stripes, hover and borders as seen below.

Example Tables

Grammar and Spelling

Make sure to proofread documents after they are completed, before submitting them for review. Accurate spelling and grammar are very important.

Terminology

When writing about technology, either software or hardware, make sure to use the same terminology as used by the developer/manufacturer. 

Frequently used verbs in software documentation include:

• Click
• Double-click
• Select
• Highlight
• Type
• Press
• Settings
• Options
• Drop-down

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. The URL the link goes to should be behind text that describes where the link goes.

Keyboard Controls

Capitalize the titles of keys on the keyboard. Keys that should be pressed simultaneously should be combined 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