Page Comparison

All articles in the ITS Knowledge Base must follow a consistent style and tone. This style guide is intended to provide a set of standards for content and formatting that should be applied to all articles. See Creating Articles for descriptions of various types of articles present in the Knowledge Base. 

...

1.0 Article Content

The content of the articles should be clear and concise. Content should be geared towards a lay audience with minimal technological experience. 

1.1 – Article Topics

Articles should focus on a single topic of interest to the intended audience of the Knowledge Base.

How-to Articles

For how-to articles, the topic will be task-oriented. Articles that contain more than one task should be broken up into two separate articles.* For example, an article such as "Changing and Resetting your Google Password" should be broken up into two articles titled "Changing your Google Password" and "Resetting your Google Password." This is done because changing a password and resetting a password are two separate tasks with two separate sets of instructions. 

Troubleshooting Articles

Troubleshooting articles should focus on helping the user solve a problem that they are having. Similar to how-to articles, troubleshooting articles should focus on a single user issue (e.g., "Cannot Connect to UConn Secure" or "Wifi Adapter Shows There is No Internet"). If your article helps the user solve a single issue, but you need to ask multiple questions to either identify the problem or provide the user with a range of possible solutions, then you can include all of that content in a single article. Typically, these types of articles have "troubleshooting" at the end of the title (e.g., "HuskyVision Troubleshooting"). 

Informational Articles

Informational articles should provide a brief overview of a topic and help orient readers so that they can understand a concept and seek more informed assistance on an issue. 

1.2 – Article Titles

How-to Article Titles

For how-to articles, we start with a gerund – a verb with the suffix "-ing" that is used as a noun (e.g., "Adding a Mass Mail Account in Outlook"). Below are some guidelines for titling how-to articles. 

• Pick one word for actionable things. Instead of titling an article "Archiving or Saving Emails..." title it "Archiving Emails..." or "Saving Emails..."

Troubleshooting Articles

For troubleshooting articles, the title should be the problem the user is trying to solve (e.g., "Printer is Flashing Red and Will Not Print").

Informational Articles

Titles for informational articles should make it clear what topic is covered in the articles. Typically, these types of articles have "overview" at the end of the title (e.g., "G Suite Overview"). 

1.3 – Labels

All articles must include labels (or metadata) – keywords that are related to the topic of the article. Labels support an effective search and group related articles together.

...

Do not mix the macros and their names, like, for example, adding an info macro and titling it "Note."

2.0 Article Formatting

The formatting of the articles should enable readers to skim the article easily and assess relevance.

2.1 – Bold Words

When you are instructing the reader to perform an action, such as clicking or entering, bold the word that corresponds to the on-screen buttons/clickable elements.
EXAMPLE 1: Click Save My Information to continue to the next screen.
EXAMPLE 2: Enter a personal email address (not your @uconn.edu) in the "Secondary Email Address" field, and click Save Changes.

2.2 – Quotation Marks

When instructing a reader to look for text on their screen, use quotation marks around the words they should be looking for.
EXAMPLE 1: Quotation marks should not be used when looking for text within a button/clickable element (see "Bold Words" above).
EXAMPLE 2: Un-check the box next to "Show Labels for Each Page."

2.3 – Headings

All headings should specifically describe what is in that section of the article. Usually in how-to articles, headings are a re-iteration of the article title. (i.e., if the article title is "Accessing Email in Windows," then the heading should be the same thing instead of something like "Accessing Email" or "Email in Windows." When applied consistently, headings help readers skim content and understand the article's organization quickly. It also enables macros within our KB to work correctly.

• All article titles should be formatted as Heading 1.

• All second level headings within the article, which mark the different sections within an article (e.g., Article Content), should be formatted as Heading 2.

• Any subheadings underneath a level 2 heading should be formatted as Heading 3, then Heading 4, and so on. 

To create headings,

1. Highlight the text. 

2. In the toolbar, click the dropdown menu that by default says "Paragraph."

3. Add headings as you see fit. Ensure that the heading style is appropriate for the level of your heading.

2.4 – Numbers and Bullets

Numbers and bullets are an effective way to highlight key steps or information and break up blocks of text into meaningful units.

• Use numbers for the steps of a process. Most how-to and troubleshooting articles have numbered steps.

• Use bullets when listing items that do not need to be performed in a certain order or when simply providing information. 

• For consistent and easy formatting, use the toolbar to set these styles. 

2.5 – Spacing

Use spacing to show what information belongs together and what is separate.

• Insert one line's worth of space between steps and paragraphs.

• For screenshots, leave no space between the image and text it illustrates, but do leave a space after the screenshot to distinguish it from the next step.

3.0 Writing and Editing

3.1 – Language

The majority of the articles in the public-facing Knowledge Base are intended for a lay audience and should be written in plain language. Focus on the task they are trying to accomplish from their perspective and less on the technical language used to describe it.
EXAMPLE:

• Use task-oriented, plain language: Log in on the Single Sign On screen with your NetID and NetID password.

• Avoid an overly technical description: Authenticate into CAS with your NetID credentials.

3.2 – Images

Images can impart a lot of information quickly. However, they can become outdated quickly and add a lot of length to an article. Use an image when it clarifies a more complicated action or conveys a lot of information quickly. When considering how and when to use an image, follow these guidelines: 

When to Use Images

• Use images when the instructional steps are complex or several actions are incorporated into a step or into many steps.

• Ask yourself: Is the image really necessary? Can I just use plain text to get the same message across? 

• Avoid using images of text when possible.

Consistency of Image Capture Method

• All KB contributors should be using a standard image capturing method to allow for consistency among the KB articles.

  • For PC, use the snipping tool. Make sure you take the snip at a high enough zoom so that the resolution is maintained once you place your image into the article. Add callouts as necessary in PowerPoint (see section 4.2 of this style guide). 

  • For Mac, use the print screen function and crop the image. Make sure that the section you want to crop is not too small and that it will retain a high resolution when you input the image to your article. Add callouts as necessary in PowerPoint (see section 4.2 of this style guide).

Image Size

• Screenshots should be big enough to clearly display image contents without having to click on or enlarge the image. 

• Ensure that you size the image in Confluence so it does not extend past the text around it, and so it is not too small either. Judgement is key here.

Image Borders

• Images, especially those with a white background, may get lost on a white page. Add a black border around all images.

Image Position

• Images should always be below the explanatory text that references the image.

Alternate Text

• Use descriptive alt text when you place an image into your article and have not adequately described above the image what the user is supposed to gain from it.   

3.3 – Definitions

If you have to include a technical word to make sense of the topic, find a way to define it for the reader. Some strategies include:

• Use context to imply the meaning.

                EXAMPLE: With two-factor authentication, you will log into a service with your NetID and password and then verify your identify on a second device.

• Explain the term in a clause following its mention.

                EXAMPLE: You can create an email alias (the portion of your email address to the left of @uconn.edu) that is different from the name originally assigned by the University.

3.4 – Acronyms

On the first mention of an acronym, spell out the phrase, and then follow it with the acronym in parentheses. Once you have spelled out the phrase, you can continue to use the acronym.
EXAMPLE: Many services are behind the Central Authentication Service (CAS).

3.5 – Contractions

Avoid using contractions. We use a more formal tone, and contractions are more informal.

3.6 – Capitalization

Capitalize names and proper nouns (names used for an individual person, place, or organization). Words like 'faculty' and 'staff' should not be capitalized.

When writing instructions and referring to a word that is capitalized on the screen or device, you can capitalize the word to be consistent with the user's experience.

• EXAMPLE: Go to the "My Settings & Devices" section to add a backup device.

If the words you are referring to on the screen or device are in lowercase, write the instructions accordingly. 

3.7 – Punctuation

In general, use commas, periods, semi-colons, and hyphens appropriately. Avoid exclamation marks, which do not fit the tone of a Knowledge Base article. 

One common punctuation mistake is to separate two complete sentences with a comma. Make sure to use a period or join with a comma and conjunction. 

Mistake: Enter your full name, then click OK.
Correct: Enter your full name. Then click OK.   OR    Enter your full name, and then click OK.

For lists and numbered steps, use a period if it is a complete sentence or completes a sentence started by the lead-in phrase.

EXAMPLE 1: Use a period.
You can verify your identity on the Duo Mobile App by

• getting a Push Notification and selecting Approve. 

• entering the passcode on the app.

• having the service call you.

EXAMPLE 2. No period

Stop by the front desk of the ITS Help Center for onboarding assistance.

• Software access and installation

• Virus detection and removal

• Email set up

• Wireless connectivity

• Static IP assignment

3.8 – Standardized Terms and Phrases

The following words or phrases should be written or used in the following, standard ways when referring to them in your articles. For example, refer to the help center as the "ITS Help Center" or "Help Center," but do not refer to it as the "help desk" or "Husky Tech."

3.9 – Article Length

Articles should be kept short and require minimal scrolling. If there are multiple sub-sections in the article and the article is long (scrolling required), consider adding anchors to the subheadings to facilitate quick access to relevant information.

...

There are a number of helpful keyboard shortcuts that will make your article writing process faster if you would like to use them. 

4.0 Accessibility

Because we are a public-facing and all-inclusive service, we must ensure that the content of our Knowledge Base is accessible for all users. Many of our users require assistive technology, such as screen readers. To ensure that our knowledge base is accessible for people using assistive technology, we need to follow the guidelines below. 

4.1 – Alternate Text 

What is Alternate Text? 

Alternate text, or alt text, is a textual description of an image. Alt text is applicable when inserting pictures into an article. It is text that describes what knowledge or functionality the reader is supposed to gain from the inserted image. Alt text is only helpful when it fully describes the form and function of the image and is not redundant. 

Good alternative text provides the information conveyed in an image, including all text seen in the image and relevant details. It can be difficult to choose where to focus the description, so here are a few rules of thumb:

• If an image is meaningful, it must have alternate text. Not providing alternate text means that users who cannot see the image will miss information.

• Focus on form and function. Form or context often tells us what aspects of the image are most important. Similarly, function can tell us how to describe the image. A magnifying glass icon that serves as a search button should be described as a search button.

If stuck formulating alternate text, consider how to you might describe the image to someone over the phone.

For Images With Explanatory Text Above Them

For images that have their purpose adequately described above it, we use null alt text so that assistive technology will skip over the image. We do not add a descriptive alt tag in this case because that would be redundant. Null alt text can be indicated as alt="".

EXAMPLE:

1. Make the text font Arial and the font size 12.

2. Make sure bold is selected and make sure that your highlight color is yellow.
   Image Added
   Alt= “”

For Images Without Explanatory Text Above Them

Use a descriptive alt tag when you place an image into your article and have not adequately described above it what the user is supposed to gain from the image. A descriptive alt tag should describe the purpose of the image or what knowledge the user is supposed to gain from the image. 

Inserting Alt Text

Once your picture has been inserted into your article,

1. Left-click on the picture.

2. Select Properties.

3. Enter your alt text.

4. Click Save. 

5. Click Update or Publish in the bottom right corner of the screen (depending on which phase of article editing you are in).

6. Click Edit to re-enter the editing window. Make sure that your alt text is present.

4.2 – Call Outs in Screenshots

A call out in a screenshot is any shape used to delineate a specific section of the screenshot that you want a user to focus on. Callouts should be mentioned in the explanatory text above when appropriate. When using multiple callouts in a single image, it is imperative that the callouts be differentiated based on shape and not color (for those users that are color vision impaired). 

EXAMPLE: You can search for macros (rectangle) or you can browse through the macros using the left-side list of macros (curly brace).                                                                                                                                                      

...

4.3 – Tables

To make tables as accessible as possible, set the top row as a "Heading Row" and/or the first column as a "Heading Column."

...

Setting these cells as heading cells allows assistive technology like screen readers to associate data cells with their appropriate header cells. This is necessary for screen reader users to understand the relationship between data cells and header cells. Avoid images of tables, as none of the accessibility information will be available to users.

Table view must also be set to Responsive. This allows the table's text to reflow, making it accessible for users who may zoom in to view text. It is also helpful for mobile users.

...

Avoid using merged cells in the body of your table. While screen readers are capable of correctly interpreting merged cells for column headers, they are unable to correctly interpret merged table data cells. 

4.4 - Meaningful Link Text

Avoid writing "Click Here" and similar phrases for links. Instead, have the link text describe the link destination. In addition to being more accessible, it helps with your Google search rankings. For example, “For more information about our admissions process click here...” should be written as “For more information about our admissions process...“

4.5 - Layout Tables and Columns

Instead of using a layout table for information, consider using the Columns macro. When screen reader users encounter a table with data cells coded using <td>, they expect to also hear information about table headers (<th>). Layout tables do not have table headers. Typically, in HTML, a layout table can be assigned the role="presentation" so that screen readers will read the content of layout tables as text, rather than as a table; this is not possible through Confluence. Because this is not a function Confluence supports, it is better to use the Columns macro to visually style the page. When using the Columns macro, you will be asked to input the column width in pixels or in percentages. Use percentages so that the column content will be responsive. Add additional columns by inserting additional macros below the initial macro.

4.6 - Color Contrast

Making text high enough contrast against its background is vital for users who are colorblind or who may have low vision. These users may not be able to distinguish text if it is too similar in brightness to its background.  One good tool to check for color contrast is the Colour Contrast Analyser. To download Colour Contrast Analyser, click the Download button and choose CCA-Setup-3.0.1.exe. Text should meet a ratio of 4.5:1 between the foreground and background colors. This will cause the WCAG 2.1 results heading 1.4.3 Contrast (Minimum) (AA) to have green checkmarks. If the results show a red X, then the contrast is not high enough and you need to adjust the text or the background's color.

4.7 - Color Dependence

If you choose to color-code information, be sure to indicate the color-code's purpose through text or images. For example, instead of coding all incorrect table data cells as red, we could code them as red and add an X to each incorrect cell. This is vital for people who are blind, have low vision, or are colorblind. Users without full vision capabilities may not be able to distinguish color-based information, so it must be supplemented with text or images.

Related Articles

...