Knowledge base article review and approval

The process for reviewing and approving knowledge base articles.

• Article Reviewers
• Article Review Process
• Article Approval Process

All TDNext users can create articles in the knowledge base, but only certain users have the ability to review, approve, and publish knowledge base articles to the TeamDynamix knowledge base. This article is directed at users with article review and approval privileges, but can also be useful for article authors as well.

Short Version (for KB reviewers)

1. Review article to ensure it meets standards for spelling, clarity, accessibility, formatting, copyright, and placement.
2. If article meets standards
   1. Change article owner to your department.
   2. Approve and publish to KB
3. If article needs work
   1. Communicate with article author to resolve issues

Article Reviewers

KB Reviewers

Most areas will have an assigned KB Reviewer, who has the responsibility of reviewing, editing, approving/rejecting, and publishing articles written for their area (e.g., Network Operations, IT Support Services).

KB Reviewers will need to periodically check articles pending review in their area to make sure that articles pending review are addressed in a timely manner.

KB Reviewers need to have excellent writing and editing skills, as well as training in the article review and approval process. Contact the TeamDynamix administrator for information on becoming a KB Reviewer.

Article Review Process

You can view all articles that have been submitted for review by clicking on "Articles Pending Review". You will need to look for articles written by people in your area.

KB articles should be reviewed for the following:

1. Spelling and grammar
2. Style, clarity, and readability
3. Appropriateness for audience
4. Accessibility
5. HTML formatting
6. Copyright issues
7. Appropriate placement

Spelling and Grammar

At the very least, all articles need to be spell-checked. However, articles should be read in detail for proper grammar, punctuation, and word usage as well. If you aren't sure about proper usage and grammar, don't hesitate to ask a KB Lead.

Style, Clarity, and Readability

Most articles in the knowledge base are at least semi-technical in nature, and the writing style should reflect that. Here are a few tips:

• Avoid overly informal or slang language
• Use a somewhat formal writing style, without being stiff
• Avoid using a too personal, chatty style
• Avoid passive language, and use action words when possible
• Using personal pronouns such as "you" is acceptable. It is better to speak directly to the user, as long as it is not too informal.
• Avoid long-winded, complex sentences. It is generally better to break things into short sentences or even bulleted lists.
• Use the University Writing Style Guide for proper usage of words, phrases, and capitalization of campus-related items

Examples

• Poor: "The end user should then click their mouse on the 'Edit' button in order to access the page that allows them to make changes to their page's content."
  • Passive language; long complex sentences; too impersonal; mixed singular and plural
• Good: "Click the 'Edit' button to make changes to your page's content."
  • Simpler; more direct; uses action-oriented language; addresses the user directly

Appropriateness for Audience

A KB article on "Connecting to the wireless network" directed at the general campus community should be written differently than an article on "Allowing OCSP to validate code certificates used on the eduroam setup wizard" that is intended only for network operations analysts.

For articles directed at the general campus community, strive to eliminate technical jargon and replace it with commonly understood words. In many cases, overly technical explanations can be removed altogether from articles.

For articles directed at a highly technical audience, leave the technical explanations as is, on the assumption that the technicians reading the article will understand it. Focus instead on readability and clarity. Even technical audiences appreciate articles written simply and clearly, with action-oriented language.

Accessibility

In accordance with state and federal law, as well as CSU policy, all content must be Section 508 compliant.

The two main areas that will likely cause accessibility issues are images and videos, though a few other things may be problematic as well (e.g., using font colors).

Images

All images must have alternative text (ALT text) that explains the content of the image to visually impaired users. In many cases, images in KB articles will be screenshots, and the alternative text must describe the content of the screenshot. For example: "Screenshot of the Alternative Text field in the Image Properties dialog." It is NOT acceptable to put "Image" or "Photo" in the alternative text.

Fortunately, TD makes adding ALT text simple, by providing an Alternative Text field in the Image Properties dialog box. USE IT.

Videos

With videos, the opposite issue arises. Instead of being inaccessible to the visually impaired, videos tend to be inaccessible to the hearing impaired. As a result, captions or transcripts are required for all videos. Fortunately, YouTube has excellent automatic captioning that will automatically add captions to most videos. Quality does vary, but you can manually edit captions as well.

Font Colors

Avoid using font colors because color-blind individuals may not be able to see them. Use bold or italic instead to make the text stand out.

HTML Formatting

Importing articles from other HTML pages (such as the campus wiki) is a quick way to get content into the KB. Unfortunately, pasting HTML into TD's article editor will often bring along unwanted formatting styles. Links and images will also point to the wrong place.

There is no perfect, "Easy Button", way around this. Perhaps the most straightforward thing to do is use the "Paste as Text" button in the TD editor. This will strip out all formatting, images, and links. You will need to recreate headings, bulleted lists, links, and images, but it guarantees that the content is clean and properly formatted.

Copyright Issues

It is often tempting for article authors to simply copy and paste content from other sites into the KB. It is fine to link to content on the web or even embed YouTube videos, but it is not acceptable to copy and paste content wholesale into the KB. For public articles, a simple Google search would reveal the copyright violation. Quoting with attribution is fine, as long as the quoted text is a reasonable length (no more than a couple of paragraphs). 

Appropriate Placement

Authors who are not very familiar with TeamDynamix may not know exactly where an article belongs in the knowledge base. Sometimes, they just create their articles at the top level of the KB. One job of the KB Reviewer is to check to make sure that articles are in the appropriate place in the KB.

To change the placement of an article, go to the article settings and search for the correct category. Since TD doesn't let you browse through the KB to find the right location, it may help to do that before changing the category so that you already know where the article should go. If in doubt, contact a KB Lead or TeamDynamix administrator.

Article Approval Process

Only KB reviewers and leads can approve KB articles.

Approving an Article

Articles should only be approved if they meet the standards listed above when reviewed. The KB reviewer should do what they can to clean up the article so that they can approve it.

Do not approve articles by clicking on the big "Approve" button, since this does not publish the article to the KB.

Instead, edit the article and go to "Settings". There, you will need to do 5 things:

1. Change the Status to "Approved"
2. Check "Published to KB"
3. Add a review date. All articles should be reviewed a minimum of once a year.
4. Change the owner to your department 
   • Non-owners will still be able to edit the article. Changing the owner to a group lets others know who to contact if the original creator leaves the university. 
5. Check "Notify Owner on Feedback"
   • This will notify you of any feedback on the article so that you can address updates, broken links, etc. if needed. 

"Rejecting" an Article

If an article needs a lot of work, needs to be completely rewritten, or clearly violates copyright, the KB reviewer should not reject the article. Rejecting the article will result in the owner not being able to resubmit the article.

Instead, follow these steps:

1. Click on the "Edit Article" button
2. Click on the "Settings" tab
3. Scroll down to "Status" and change the status of the article to "Not Submitted"
4. Contact the article owner and inform them that their article needs work before it can be approved, along with an explanation of what exactly needs to be done. They are not notified when you change the article status.