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.
...
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.
...
Because we are a public facing and all-inclusive service, we need to 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 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?
Alt 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. However, alt Alt text is only helpful when it fully describes the form and function of the image and is not redundant.
| 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 a NULL alt tag that the assistive technology will skip over. We do not add a descriptive alt tag in this case because that would be redundant.
EXAMPLE:
- 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 text = “”
For images without explanatory text above them
In this case, use a descriptive alt tag 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. 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, left click on the picture. Then select "properties." Type in your alt text. Then click save. Click Update or publish in the bottom right corner of the screen (depending on which phase of article editing you are in) and then click edit to re-enter into the editing window. Make sure that your alt text is present.
4.2 – Call Outs in Screenshots
A call out in a screen shot is any shape used to delineate a specific section of the screenshot that you want a user to focus on. Call outs should be mentioned in the explanatory text above when appropriate. When using multiple call outs in a single image, it is imperative that the call outs be differentiated based on shape, not color (for those users that are color vision impaired).
EXAMPLE:
...
Good alternative text provides the information conveyed in the 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.
| 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="".
EXAMPLE:
- 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
In this case, use a descriptive alt tag 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. 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, left click on the picture. Then select "properties." Type in your alt text. Then click save. Click Update or publish in the bottom right corner of the screen (depending on which phase of article editing you are in) and then click edit to re-enter into the editing window. Make sure that your alt text is present.
4.2 – Call Outs in Screenshots
A call out in a screen shot is any shape used to delineate a specific section of the screenshot that you want a user to focus on. Call outs should be mentioned in the explanatory text above when appropriate. When using multiple call outs in a single image, it is imperative that the call outs be differentiated based on shape, 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
In order 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.
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.
Finally, if you choose to color-code cells, be sure to indicate the color-code's purpose through text or images. For example, instead of coding all incorrect data cells as red, we could code them as red and add an X to each incorrect cell.