Correct word usage, spelling, grammar, and consistency is important in TeamDynamix (TDX) knowledge base articles and service descriptions to ensure clarity and understanding of the information.
Styles for Commonly Used Words and Phrases
Articles can be created and edited by TeamDynamix technicians with access to the knowledge base (KB). If you need access, click the Schedule a Time for TDX Service Catalog Development button on the right.
Before creating a new 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.
Steps to create a new knowledge base article
To create a new knowledge base article:
- 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.
- 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.
- 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.
- 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.
- Complete the Subject field with the title or main heading for the article.
- 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.
- 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.
- Use the Tags field to add search tags.
- Use the Status dropdown to indicate whether the article is Not Submitted, Submitted, Approved, Rejected, or Archived.
- If the article has a status of Approved and is ready to be public in the knowledge base, check the Published to KB checkbox.
- Next Review Date is useful as a reminder for article reviews.
- 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.
- 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.
- Check the Notify Owner on Feedback checkbox so that the owner will know when feedback has been left on the article.
- Complete the Audience field. Examples: “University faculty, staff, and students”, “University graduate students”, “TeamDynamix technicians”
- 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.
- The Responsible Group field can be used for additional entities besides those in the Responsible Group/SME field.
- 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.
Proof the new article
After saving, click the article title in the breadcrumbs at the top to view the article. You will want to check the article to make sure it looks as intended. Content can appear as formatted differently when viewed as the published article than it does when editing.
- All the links in the article should be checked to make sure the URLs entered are correct.
- Read through all the sections and determine if any of the information belongs in a different section or if the sections should be in a different, more logical order.
- Does the article make sense out of context from other articles?
- Are there links to a main/hub article and to other related articles both in the content and in related articles?
It is good practice to have someone else (or multiple people) on your team to proofread the article. It can be especially helpful if the proofreader is unfamiliar with the material to determine if the article is clear and easily understood.
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.
Draft Summary
The Draft Summary field, located below the Body field (main content field) when editing an article, is available to add notes and details (a brief summary) about the changes and edits that were made in the current draft of the article. If the edit includes major changes, it is advisable to include notes in the Draft Summary. Minor edits may also be recorded in the Draft Summary if desired. Each Draft Summary will be displayed in the article's Feed and only visible to content authors. The Draft Summary should not be confused with the article's Summary.
Settings
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.
Related services and articles
Related Services and Related Articles can be set up under the Related Services and Related Articles tabs.
Saving
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.
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.
Creating the parts of an article
All parts of the article should be ADA compliant.
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:
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:
- Click Edit Article and the Files tab.
- Click the Add button.
- Click Browse to select a file to upload.
- Click the Upload button.
- Click the Add button.
- Close the Add Attachments window.
To ensure web accessibility, see W3C's pages on: