Additions and revisions to the Knowledge Base should follow formatting guidelines to ensure that a professional, uniform language and style format is maintained across the resource. Consistency improves the accessibility of the Knowledge Base by enabling readers to identify relevant points and quickly locate the information they seek.
In this article:
| Table of Contents | ||||
|---|---|---|---|---|
|
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: 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."
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,
Highlight the text.
In the toolbar, click the dropdown menu that by default says "Paragraph."
Add headings as you see fit. Ensure that the heading style is appropriate for the level of your heading.
| Note |
|---|
All headings, regardless of type (i.e., 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
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.
...
| Info |
|---|
If you are trying to get lines of text to not have any spacing between them,
|
...
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.
...
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.
...
Capitalization
Capitalize names and proper nouns (names used for an individual person, place, or organization). Words like 'faculty' and 'staff' should not be capitalized.
...
If the words you are referring to on the screen or device are in lowercase, write the instructions accordingly.
...
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.
...
Software access and installation
Virus detection and removal
Email set up
Wireless connectivity
Static IP assignment
...
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."
...