Page Comparison

All articles in the ITS Knowledge Base will All articles in the ITS Knowledge Base will 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. Please visit Creating Articles for descriptions of the types of articles that will be written in this knowledge base. This style guide pertains to all types of articles.

...

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

...

Articles should focus on a single topic that would be of interest to the intended audience of the knowledge baseKnowledge 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 (i.e. "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 title (i.e. "HuskyVision Troubleshooting"). 

...

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

...

Titles for informational articles should make it clear what topic is covered in the articles. Typically, these types of articles will have "overview" at the end of the title or the title will ask a question that the article answers (i.e. "G Suite Overview" or "What is G Suite?"). 

...

1.3 – Labels

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

...

Article summaries are meant to help to users to user quickly assess the relevance of the of the article for their problem or question.  Article Article summaries should include two things: (1) Who the article is intended for and (2) what functionality the user can gain from the article.

EXAMPLE 1:  “This article is intended for students who are trying to "Students can set up their G Suite account for the first time." 
EXAMPLE 2: "This article is intended for studentStudents, faculty, and staff who cannot connect can resolve issues they experience when connecting to UConn Secure." 

Subsequent sentences in the summary should follow a hierarchical structure in that the most important information for the user to assess relevance is put first.

...

Topics come up while writing that may not be familiar to the user. If while writing you find that find that you mention a topic that may need further clarification and we have an article in our KB that clarifies that topic, please link that article to the page. Link the article so that it is embedded in the text that you are writing (ie.eg., "When you are are Changing Your NetID Password, please follow the password guidelines"). You may need to change the way the link displays so that it syntactically fits with your writing (ie.eg., "You must have have Password Recovery Options set up in order to reset a forgotten password."). 

To insert these links to your article, click

1. Click on the link icon (Image Modified) in the toolbar at the top of the edit window.

...

2. Click Search.
3. Enter the name of the article in Confluence that you want to link.
4. At the bottom of that window, you can change how the link appears in your article by altering the "link text."

...

2. Click Insert. 

Avoid using phrases such as "Click Here", "Read More", or "Learn More" as the sole link text.  This does These phrases do not provide any context for users with assistive technology, such as a screen reader user.

...

If you need to link to a page outside of Confluence, like netid.uconn.edu, please insert the link without the "http://" by altering the link text. Additionally please

Furthermore, you should use the actual link if the link is small, like like email.uconn.edu. For longer links, you will need to change the link text so that the link takes up less space on the article and provides context for assistive technology users. 

To insert these links to your article, click

1. Click on the link icon (Image Modified) in the toolbar at the top of the edit window.
2. Click Web Link

...

1. .
2. Enter or copy

...

1. /paste the link into the

...

1. Address

...

1. field.
2. If needed, you can change how the link appears in your article by altering the

...

1. link text.

...

2. Click Insert. 

1.6 – Note/Info/Tip/Warning Macros

When inserting these macros, add the name of the macro (Note, Info, Tip, or Warning) under the "optional title" section of the macro edit window.

To access the macro edit window, left

1. Left click on the macro

...

1. .
2. Click edit. 

See below for examples of what each Macro title should look like. 

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

...

When you are instructing the reader to perform an action, such as clicking or entering, you should 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."

...

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

Create headings by highlighting To create headings,

1. Highlight the text.

...

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

3. You can choose to add headings as you see fit

...

1. . Ensure that the heading style is appropriate for the level of your heading.

   Note
   title Note
   All headings, regardless of which type of heading they are (Heading 1, Heading 2, Heading 3, etc.) should follow standard capitalization practices for titles such that the major words in the title are capitalized. For example, a heading should read "Helpful Functionalities of the Confluence Editing Window" instead of "Helpful functionalities of the confluence editing window."

   
   

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 number numbers for the steps of a process. Most How-To and Troubleshooting articles will have numbered steps.
• Use bullets when you are 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.

  Info
  title Info
  If you are trying to get lines of text to not have any spacing between them,

...

• Place the cursor at the end of the preceding line of text.  Hold down the Shift key.  Press Enter. The cursor will shift to the next line without spacing.

  
  

3.0 Writing and Editing

3.1 – Language

...

• Use task-oriented, plain language: Login 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.

...

Images can impart a lot of information quickly. However, they can also become outdated quickly and add a lot of length to an article. Choose to 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. This will allow for consistency among the KB articles.

  • For PC

...

• • , use the snipping tool. Make sure you take your snip at a high enough zoom so that the resolution is maintained once you place your image into the article. Add call outs  as necessary in power point (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 call outs as necessary in power

...

• • point (see section 4.2 of this style guide).

Image

...

Size

• Screenshots should be big enough to get the point across without having to click on or enlarge the image. Users should be able to clearly view the image contents without having to click on it.

...

• Ensure that you size the image in Confluence so that it does not extend past the text around it, and so that 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

...

• . You should add a black border around

...

• all images.

Image Position

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

Alternate Text

• For images where there is explanatory text above the images:
  • In this case the explanation is already above the image, so to avoid redundancy we will use null alt text. To put in null alt text, just put double quotes "" into the alt text dialogue box. 
  • If your image requires the user to pay attention to multiple parts of an image, please use image call outs (see section 4.2 of this style guide). 
• For images that do not have explanatory text above the image:
  
  • In this case, 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 the image.   

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:

...

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

...

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

3.5 – Contractions

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

...

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

When you are writing instructions and are 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, you should write 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. 

...

...

Keep paragraphs short - no more than four to five sentences. Use formatting elements such as bullets, numbers, and note sections to highlight relevant information and break text up into units that are easy to follow. (See Numbers and Bullets in the formatting section). Organize and separate sections with subheadings. This will help readers skim the content and find the desired section (See headings in the formatting section.)

...

Macros are visuals that dynamically organize your content and allow you to draw attention to aspects of your content that you want to have stand out to your readers. They are especially useful when you have a piece of information that is important for your readers but that does not fit into the rest of your article. Additionally, macros provide additional functionality to your articles, enabling you to do things like link pages, condense your content into accordion folders, insert page anchors, create and insert project timelines, and much more. See

3.11 – Spacing

Confluence headings have built in spacing, but make sure you take out as much space between sections as possible. This helps the reader flow through the information more easily.

...

Because we are a public facing and all-inclusive service, we need to 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. In order to ensure To ensure that our knowledge base is accessible for people using assistive technology, we need to follow the guidelines below. 

...

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 Modified
   Alt= “”

For images without explanatory text above them

...

Once your picture has been inserted into your article, left 

1. Left-click on the picture.

...

2. Select properties.

...

2. Enter your alt text.

...

2. Click save. 
3. Click Update or publish in the bottom right corner of the screen (depending on which phase of article editing you are in)

...

1. .
2. Click edit to re-enter into the editing window. Make sure that your alt text is present.

4.2 – Call Outs in Screenshots

...

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

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

Image RemovedImage Added

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

Image RemovedImage Added

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.

...

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 will help with your Google search rankings. For example, “For more information about our admissions process process click here” could be better as “More information about our admissions process“.

...

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 could 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 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 check marks.  If the results show a red x, then the contrast is not high enough and you will need to adjust the text or the background's color.

...

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