Using the TeamDynamix editor to create accessible knowledge base articles and service descriptions

The guidance in these documents concerns using correct grammar and punctuation, ensuring ADA compliance, and keeping a consistent style in TeamDynamix (TDX) knowledge base articles and service descriptions to ensure university brand integrity. Follow the guidance on headings, images, links, videos, and PDFs to maintain compliance in knowledge articles and service descriptions that you create or edit.

ADA Accessibility | Headings | Links | Lists | Acronyms | Images | Videos | PDFs

ADA Accessibility

Knowledge articles and service descriptions should follow accessibility guidelines to allow people with disabilities to access them in various ways, such as with screen readers and voice recognition software. Ensuring web accessibility for people with disabilities is a priority.

Web Content Accessibility Guidelines (WCAG), developed by the World Wide Web Consortium (W3C) Web Accessibility Initiative (WAI), is an international standard for web content accessibility. There are three levels of conformance to the guidelines, Levels A, AA, and AAA. We strive to meet Level AAA, the highest level. Follow the guidance on headings, images, links, videos, and PDFs to maintain compliance in knowledge articles and service descriptions that you create or edit.

Headings

Use headings in an article or service description when needed to organize the information into sections for clarity and readability. Descriptive headings are important for ADA accessibility as they help to find specific content and become oriented in the page. Put the most important information at the beginning of each heading.

The requirement for Level AA is that headings must describe the topic or purpose, but for Level AAA, section headings must be used to organize the content of the page.

To ensure web accessibility, see W3C's pages on:

• Headings and Labels
• Providing descriptive headings
• Section headings

Use HTML heading tags for all headings. Article Subject fields and service Name fields are rendered with Heading 1 (H2) tags, so the main headings within the article Body field or service Long Description field should be Heading 2. Headings beneath those should be Heading 3 and so on. Don't skip headings; use them in descending order. Heading 1 should not be used in TDX articles and service descriptions; heading 2 will be the highest level used in the Body or Long Description.

Create a heading in a knowledge base article or service description

In the TDX editor, click into the heading text, click the Paragraph Format dropdown (default displays "Normal"), and select the heading level.

Use the Special Container style in the TDX editor with H2 headings in an article.

To remove the Special Container style, click in the text and select Special Container again from the dropdown. Lower level headings should not use the Special Container style.

Links

A link should make sense when read on its own, out of the context. Assistive technology can provide a list of links on the page, and users can choose from the list.

The minimum requirement for Level A is that the purpose of each link can be determined from the link text itself or from the link text within the context of the surrounding text, but for Level AAA, the purpose of each link must be able to be identified from the link text alone.

"Click here" or "More information" as link text is not ADA compliant. This text does not describe the link's destination.

To ensure web accessibility, see W3C's pages on:

• Providing link text that describes the purpose of a link
• Providing link text that describes the purpose of a link for anchor elements
• Link Purpose (Link Only) (Level AAA)
• Link Purpose (In Context) (Level A)
• Failure of Success Criterion 2.4.9 due to using a non-specific link such as "click here" or "more" without a mechanism to change the link text to specific text

Links should also follow the knowledge base standards:

• External links should open in a new window/tab.
• Bold links that are within a sentence.

Create or edit a link in a knowledge base article or service description

Create a link in an article or service description by selecting the link text and clicking the Link button. Copy the URL of the link target, paste into the URL field, and click OK.

To find the URL of a knowledge base article to link to, open the article in a browser, and copy the link.

To have the link open in a new window or tab, select the Target tab when creating a link, click the Target dropdown, and select New Window (_blank).

To edit an existing link, right-click in the linked text, and click Edit Link.

Links that are set in Microsoft Word will carry over when copy/pasted.

Using named anchors to link within the article

Named anchors are markers that can be placed within an article to link to that specific section.

To place named anchors in the article, click to place the cursor in the text where the anchor will be located. Click the Anchor button. Type a name in the Anchor Name field.

To create a named anchor link, select the link text, click the Link button, and from the Link Type dropdown, select Link to anchor in the text. From the By anchor name dropdown, select an anchor from the list of anchors that were previously placed in the article.

To link to a named anchor from a different article, open the article in a browser, click on the anchor link, and use that URL for the link.

Bulleted and Numbered Lists

Only use a numbered list for items that are in sequential order. If the list does not have an order, use bullets.

Create an actual bulleted or numbered list for list items; don't type the numbers or use special characters as bullets.

Make sure bulleted and numbered lists are parallel, that each item uses the same sentence structure. For example, all the items might be complete sentences or phrases beginning with a verb in the same tense.

Use punctuation at the end of complete sentences in a list.

Create a list in a knowledge base article or service description

To create a bulleted or numbered list, click the Insert/Remove Numbered List or Insert/Remove Bulleted List button. Pressing Enter after each item will create a new bullet or number. Press Enter again to end the list.

You can also select lines of existing text and click one of the list buttons to convert the lines to a list.

To add a line break in a list, hold down Shift and press Enter.

For nested bulleted or numbered lists, select the items to nest, and click the Increase Indent button.

Acronyms, Abbreviations, and Unusual Words

On first use of an acronym or abbreviation, the term should be spelled out with the acronym in parentheses following the spelled-out term. For later uses, the acronym or abbreviation can be used alone.

To ensure web accessibility, see W3C's pages on:

• Abbreviations
• Providing the first use of an abbreviation immediately before or after the expanded form

An "unusual word" may have several definitions, but one specific definition must be known for clarity of the content. Jargon and idiomatic expressions should be treated the same as unusual words. Any unusual words or jargon that is used in an article or service description should be added to the glossary, and the article should be linked to the glossary.

Try NOT to use jargon or overly technical terms in articles for the general public.

To ensure web accessibility, see W3C's pages on:

• Providing the definition of a word or phrase used in an unusual or restricted way
• Providing a glossary
• Linking to a glossary

IT Services Glossary

Any unusual words or jargon that is used in an article or service description should be added to the glossary, and the article should be linked to the glossary.

Images

Knowledge articles should only have relevant images that contain information that adds to the text content. Do not use purely decorative images that do not contribute to the understanding of the content. Do not use images of text if at all possible. Service descriptions will typically not contain any images.

All images must have an alt tag (alternate text) with the appropriate text to describe the image.

Alternate text for screenshots showing where to click should describe the location of the link or button on the screen.

To ensure web accessibility, see W3C's pages on:

• Using alt attributes on img elements.
• Providing short text alternative for non-text content that serves the same purpose and presents the same information as the non-text content.

Insert an image in a knowledge base article or service description

Saving images and uploading them to TDX to insert into an article usually has better results than copying and pasting the image into the editor.

To upload an image to display in an article and include the alt tag:

1. Click the Image button to insert an image, or select an image and click the Image button to change the image information. The Image Properties window will open.
2. Click the Upload tab in the Image Properties window to upload an image.
3. Click Browse to find the image file.
4. Click Send it to the Server to upload the image.
5. Under the Image Info tab, complete the Alternative Text field with a description of the image that includes any depicted text, instructions, or other information. All images must have alt tags!
6. Also under the Image Info tab, the height and width can be changed. A Lock Ratio button is available.
7. To make the image a link, under the Link tab, type the link URL in the URL field. Be sure to describe the link in the alternative text.
8. To have the link open in a new window/tab, select New Window from the Target dropdown under the Link tab.

Tables

An issue with tables in TeamDynamix might cause the table cell contents to break words when wrapping text. Setting a percentage for cell width in the first table cell will usually fix this problem.

Videos

Videos should have transcripts and captions. To achieve Level AAA compliance, videos must have an alternative that is fully available in text form and that is clearly labeled as an alternative. (An audio alternative will only achieve Level AA compliance.) Full descriptions should be provided of all visual information, including visual context, actions and expressions of actors, and any other visual material, as well as descriptions of non-speech sounds. Transcripts of all dialogue should be included. The sequence of descriptions and dialogue transcripts must be the same as the sequence in the synchronized media itself.

To ensure web accessibility, see W3C's pages on:

• Media Alternative (Prerecorded) (Level AAA)
• Providing an alternative for time-based media
• Audio Description (Prerecorded) (Level AA)
• Providing a second, user-selectable, audio track that includes audio descriptions
• Audio Description or Media Alternative (Prerecorded) (Level A)

PDFs and Attaching Files

Attach associated files such as PDFs to articles. Make sure all PDFs are ADA accessible.

Attach a file to a knowledge base article or service description

To attach a file to an article:

1. Click Edit Article and the Files tab.
2. Click the Add button.
3. Click Browse to select a file to upload.
4. Click the Upload button.
5. Click the Add button.
6. Close the Add Attachments window.

To ensure web accessibility, see W3C's pages on:

• Create Accessible PDFs
• Applying text alternatives to images with the Alt entry in PDF documents