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.
...
Articles should focus on a single topic that would be 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.
...
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 +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.
...
See below for examples of what each Macro title should look like.
***Please do not mix the macros and their names, like 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.
...
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."
...
Create headings by highlighting the text. Then, in the toolbar, click the dropdown menu that by default says "Paragraph." You can choose to add headings as you see fit, just ensure that the heading style is appropriate for level of your heading.
| 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
...
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.
...
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 Macros: Understanding and Inserting Dynamic Content
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.
...
| Note | ||
|---|---|---|
| ||
All inserted pictures in the knowledge base are required to have alt text. |
For
...
images with explanatory text above them
For images that have the purpose of the image adequately described above the image, 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="".
...
- Make the text font Arial and the font size 12.
- Make sure bold is selected and make sure that your highlight color is yellow
Alt= “”
For images without explanatory text above them
...
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
...
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.
...