Format Guide: UConn Knowledge Base

Additions and revisions to the Knowledge Base should follow formatting guidelines to ensure that professional, uniform language and style is maintained across the resource.

In this article:

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.

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

Numbered and Bulleted Lists

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. 

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