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.
...
Linking to Other Confluence Articles
Topics may come up while writing that may are not be familiar to the user. If while writing you find that you mention a topic that may need further clarification and we have an article in our KB that clarifies that topic, please link that article to the page. Link the article so that it is embedded ; embed the link in the text that you are writing (e.g., "When you are Changing Your NetID Password, please follow the password guidelines"). You may need to change the way the link displays so that it syntactically fits with your writing (e.g., "You must have Password Recovery Options set up in order to reset a forgotten password.").
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 in Confluence 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.
Linking to
...
Websites Outside of Confluence
If you need to To link to a page outside of Confluence, like netid.uconn.edu, insert the link without the "http://" by altering the link text.
Furthermore, you should use Use the actual link if the link is small, like email.uconn.edu. For longer links, you will need to change the link text so that the link it takes up less space on the article and provides context for assistive technology users.
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.
...
See below for examples of what each Macro title should look like.
Do not mix the macros and their names, like, for example, adding an info macro and titling it "Note."
...
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."
...
- Highlight the text.
- In the toolbar, click the dropdown menu that by default says "Paragraph."
You can choose to add headings as you see fit. Ensure that the heading style is appropriate for the level of your heading.
Note title 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
...
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.
...