Creating and editing knowledge articles

Articles can be created and edited by TeamDynamix technicians with access to the knowledge base (KB). 

Create a new knowledge base article

Before creating a new knowledge base article, first check to see if another similar article that covers the same topic already exists. An existing article might need to be updated instead of creating a new article. Use the search to look for similar, existing articles, and look through the category where you intend to locate the new article. Typically, any new information should be added to the existing article and outdated information should be removed. You might need to contact the owner of the article to discuss updating the article.

To create a new knowledge base article:

1. After logging into TeamDynamix, navigate to the category into which the article should be placed, and click the New Article button. See our article on Categories for more information on selecting the appropriate category.
2. Click the New Article button on the right.
   If you do not see the New Article button, make sure you are signed in (check the top, right corner) and have permissions to create articles.
3. On the New Article screen, the Category field will be completed with the category where you started; this can be changed by clicking the Look Up Category button and selecting a different category.
4. The Order number that you select will determine the order in which the article is listed in the category. The Pin Article checkbox allows you to pin that article to the top of the category’s article list.
5. Complete the Subject field with the title or main heading for the article.
6. The Body field will contain the content of the article.
   • Use the instructions for the editor and follow accessibility guidelines and standard styles for headings, links, lists, acronyms, images, tables, videos, and PDFs.
   • Follow accessibility guidelines.
   • Use the Styles for Commonly Used Words and Phrases.
   • You can write articles in the TDX editor or write articles using Microsoft Word and paste the content from Word into the TDX editor using the Paste from Word button. Do not paste content directly from Word or from web pages, GitLab wiki pages, OneNote, etc. as the styles will be pasted along with the text. Text formatting including bolding, links, and bullet and numbered lists will be copied when using the Paste from Word button.
   • You can create the links in the Word document or in the TDX editor.
   • Insert images after copy/pasting text. Pasting images can cause issues.  
   • The Paste as Plain Text button will allow you to paste from anything, but you will lose any formatting, including links.
   • Create a table of contents if needed.
7. All articles should have an Article Summary. The Article Summary will be displayed with the article name in a category's listing of articles. The summary should contain information that will let the reader know if that article is what they’re looking for.
8. Use the Tags field to add search tags. Tags are important to help the search and chatbot find the right articles.
9. Use the Status dropdown to indicate whether the article is Not Submitted, Submitted, Approved, Rejected, or Archived.
10. If the article has a status of Approved and is ready to be public in the knowledge base, check the Published to KB checkbox.
11. Next Review Date is useful as a reminder for article reviews.
12. The Notify Owner of Review Date checkbox will email the article owner with a reminder for article review to see if information has changed and needs to be updated. The length of time between reviews could vary for different information.
13. All articles must have an Owner. The article owner should be someone who works with and understands the article content and can update the information in the article. The Owner will default to the person who is creating the article.
14. Check the Notify Owner on Feedback checkbox so that the owner will know when feedback has been left on the article.
15. Complete the Audience field. Examples: “University faculty, staff, and students”, “University graduate students”, “TeamDynamix technicians”
16. Begin typing a TDX technician’s name in the Responsible Group/SME field or click the Search button to see the listing of technicians.
    Note: SME is Subject Matter Expert.
17. The Responsible Group field can be used for additional entities besides those in the Responsible Group/SME field.
18. The Technician Notes field can be used for information for technicians. This field’s content will only be visible to TDX technicians.

After completing all required fields, click the Save button at the bottom.

To create related services and related articles, you must edit the new article after it has been saved. Shortcuts can also be created after the article has been saved.

Editing articles

To edit an existing knowledge base article, log into the knowledge base, navigate to the article, and click Edit Article on the right.
If the Edit Article button is not on the right, make sure you are signed in (check the top, right corner) and have permissions to edit articles.

The article will open in the editor under the Content tab where the article body can be edited. A Draft Summary field is available to add notes/details about the updates/edits that you made to the article.

Click the Settings tab to make changes to the article’s Subject, Category, Order, Summary, Tags, Status, Review Date, Owner, Audience, Responsible Group/SME, or Technician Notes.

When editing an article or service description in the TDX editor, save by clicking the Update Article button at the bottom of the page. A new version of the article will be created. You can view previous versions when in edit mode by clicking the Revisions tab at the top.

Related Services and Related Articles can be set up under the Related Services and Related Articles tabs.

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. Put the most important information at the beginning of each heading. 

Use HTML heading tags for all headings. 

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. 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.

Descriptive headings are important for ADA accessibility as they help to find specific content and become oriented in the page. 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

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. This way, assistive technology can provide a list of links on the page, and users can choose from the list.

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

Links should also follow the knowledge base standards:

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

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.

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

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 copied and pasted using the Paste from Word button.

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.
   Note: If the image has been used in a different article, you can use that image instead of uploading it again. Find the image in the article where it has been used. Right-click on the image, and select Copy Image Link/Copy image address. Paste the address into the URL field.
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!
   • Under the Image Info tab, the height and width can be changed. A Lock Ratio button is available.
   • 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.
   • To have the link open in a new window/tab, select New Window from the Target dropdown under the Link tab. Links that open external sites should open in a new window/tab.

Tables

Click the Table button to insert a table. Select the number of Rows and Columns. 

In the Headers dropdown, select First row, First column, or Both to designate which row or column contains the table headings. 

Check the boxes to Add stripes, Add hover effect, and Add borders. Use Compact style table for large tables. Complete the Caption field with an appropriately descriptive caption for the table.

Note: Tables can also be pasted from MS Word or MS Excel. 

Edit a table

To edit the table after inserting or after pasting from Word or Excel, right-click on the table, and select Table Properties.

You can also right-click on a table to insert or delete a row or column, or delete the table.

Cells can be split or merged by right-clicking and selecting Cell. Right-click and select Cell, Cell properties to make changes to the cell alignment, type, color, and more.

Troubleshooting: 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. See Making Accessible Documents for information on creating accessible PDFs.

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