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 ServiceName), 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, easiler 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.

 

Note
Not all sections headers (e.g. What materials do I need?) will be used in every article. In these cases simply remove (i.e. delete) that section from the article.

 

In this article:

 

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.

Within TDX this section header will be formatted with a H2 html style.

 

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

Within TDX this section header will be formatted with a H2 html style.

 

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.

 

Note
Sometimes you'll need to add more information to the KB article; however, when you do add extra information make sure you format it so readers know it's an aside. The templates include three different styles of asides. These are:
  • Note
  • Informative
  • Warning

 

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

Within TDX this section header will be formatted with a H2 html style.

 

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.

Within TDX this section header will be formatted with a H2 html style.

 

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.

Within TDX this section header will be formatted with a H2 html style.

 

 

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.
  • Include a line break/space before, and after an image to make sure the text is eaiser to read.
  • Highlight areas on a screenshot when appropriate. Use a Monza-ish color (RGB value: 216, 0, 65).
  • 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 desribes what the image is demonstrating (e.g. Microsoft Teams preferences dialog window screenshot).

Read the Create Effective Image article for additional information

 


Font Styles

  • Section headers: When formatting section headers the appropriate HEADER tag (e.g. H2, H3, etc.) should be selected. Nested section headers should use increasing header tags.
  • Bolded text: Bolded text should be used, typically in “how-to” articles, when telling a person what to action to do (e.g. Click, double-click, etc).
  • Italicized text: Italicized text 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: Underlined text is on a website is typically expected to reference a hyperlink, regardless of color. Try to avoid text underline for formatting text.

 

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.

 

Table Header Style

Table headers should use the following style in order to maintain consistency between articles. After a table is created, click the Source button and add the following CSS code to the relevant HTML TR, or TH attribute.

style="background-color: #00583D; color: #ffc425;"

 

Examples:

Example Table with a single header row
Header 1 Header 2
Content Content

 

Example Table with single header column
Header 1 Content
Header 2 Content
Header 3 Content

 

Example Table with header column and row
  Column Header 1
Row Header 1 Content
Row Header 2 Content

 

Numbered Lists

Use numbered lists 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).

  1. First tier
    1. Second tier
      1. Third tier

 

Bulleted Lists

Use bulleted lists 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.

  • First tier
    • Second tier
      • Third tier

 

Text Call-outs

When the need arises to emphasis specific text, usually notes, or asides, place them in formatted text boxes. Most of the existing standard templates include three different text call-out boxes "Note", "Important", and "Warning" with unique header background color to help distinguish between each.

You can either copy a formatted text box from the template, or an existing article, and paste it into the article you’re currently editing, or copy the following HTML code and within the KB article being edited, click the Source button and paste the code at the appropriate location.

 

<div style="width: 100%; border: 1px solid #00583d;">
<div style="width: 100%; border: 0px; background-color: #FFC425; padding: 5px 5px 5px 5px;"><strong>Note</strong></div>
<div style="width: 100%; border: 0px; background-color: #ffffff; padding: 5px 5px 5px 5px;">
<ul>
    <li>Lorem ipsum dolor sit amet.</li>
    <li>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin in.</li>
</ul>
</div>
</div>

 

The unordered list can  be substituted with a simple text paragraph as appropriate.

 

Order of Instructions

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.

 

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.

 

Text Formatting

Bold Text

When writing instructions bold the words that define an action (e.g. ClickSelect, etc.) Be consistent throughout the article.

 

Italicized Text

Italicized text represents what the person sees on the screen. (e.g. SaveOpen).

 

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:

 

Details

Article ID: 178
Created
Mon 6/8/20 2:43 PM
Modified
Thu 12/3/20 10:09 AM