All articles in the ITS Knowledge Base must 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. See Creating Articles for descriptions of various types of articles present in the Knowledge Base.
...
| Note |
|---|
Titles should never be presented in the form of a question. For example, if you were writing an article about Webex Events Webinars attendees, use a title like, "Managing Webex Events Webinars Registrants" instead of "How Do I Manage Webex Events Webinars Registrants?" |
1.3 – Labels
...
To insert these links to your article,
Click on the link icon in the toolbar at the top of the edit window.
Click Search.
Enter the name of the article that you want to link.
At the bottom of that window, you can change how the link appears in your article by altering the link text.
Click Insert.
Avoid using phrases such as "Click Here," "Read More," or "Learn More" as the sole link text. These phrases do not provide any context for users with assistive technology, such as a screen reader user.
...
To insert these links to your article,
Click on the link icon in the toolbar at the top of the edit window.
Click Web Link.
Enter or copy and paste the link into the Address field.
If needed, you can change how the link appears in your article by altering the link text.
Click Insert.
1.6 – Note/Info/Tip/Warning Macros
...
To access the macro edit window,
Left click on the macro.
Click edit.
See below for examples of what each Macro title should look like.
...
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.
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.
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
...
| Info |
|---|
If you are trying to get lines of text to not have any spacing between them,
|
3.0 Writing and Editing
3.1 – Language
...
For images that have their purpose adequately described above it, 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
...
Once your picture has been inserted into your article,
Left-click on the picture.
Select Properties.
Enter your alt text.
Click Save.
Click Update or Publish in the bottom right corner of the screen (depending on which phase of article editing you are in).
Click Edit to re-enter the editing window. Make sure that your alt text is present.
4.2 – Call Outs in Screenshots
...
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 can 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 who 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 checkmarks. If the results show a red X, then the contrast is not high enough and you need to adjust the text or the background's color.
...