Creating and Editing Knowledge Base Articles

Quick Links: | Article Components | Organization | Structuring and Formatting | Supporting Media | Tips & Tricks |

Before you begin...

Any TDNext user with editing permissions can create Knowledge Base articles. You can only edit articles that are owned by a group you belong to. If you are unsure if you have the proper permissions, try opening an article your department manages. If you do not see the "Edit" button on the right, fill out a request here: Request TeamDynamix Technician (TDNext) Access

Article Components

As a Knowledge Base editor/reviewer, you should be familiar with the following article components: 

• Category: This should show the location the article is in. You can change this, but it should be already filled in. 
• Order: This will order all of the articles in this category.
  • If you leave all articles at 1.0, they will be in alphabetical order.
  • You also have the option here to "Pin" the article. This is recommended if this is a highly-used article in the category.
• Subject: This is your title. Try to keep it clear, concise, and short.
  • Avoid starting titles with "How do I...?" or "How to...." Instead, try phrasing articles in terms of the action/change being made. 
  • Ex: Instead of "How Do I Install Zoom on a Personal Device?", title the article "Installing Zoom on a Personal Device".
• Body: This is where the majority of your article will be. 
• Article Summary: This is where you can expand on your title. What exactly will readers find in this article?
• Tags: Tags help chatbots and a Support Page search to locate relevant articles quickly. 
  • Ex: In the Adobe Creative Cloud article, "Photoshop" is a listed tag.
• Status: Starting out, you will set it to "Not Submitted" most likely, unless you finish the article in one sitting. See all statuses below:  
  • Not Submitted: Article is still in process, not yet done being created.
  • Submitted: Article has been fully created, just waiting on the supervisor or other approval.
  • Approved: Article must be "Approved" to be published.
  • Rejected: Article needs revisions after being submitted, and cannot yet be approved.
  • Archived: Article is no longer needed; see Archiving Articles for more information.
• Published to KB: You can only check this box once Approved.
• Next Review Date: Always add a review date!
  • Articles should be reviewed at least once a year. 
  • See Reviewing Articles for more information.
• Notify Owner of Next Review Date: This should always be checked.
• Owner: Always set the owner to your group (TDx-EAPP, TDx-ITSS, TDx-NOP, etc.) do not leave it as you!
• Notify Owner on Feedback: This should always be checked.

Article Organization

To begin creating your article, simply navigate to the category in the Knowledge Base where you want the article to appear, and click + New Article on the right.

Tip: Make sure to navigate to the exact spot where you want the article to appear before clicking + New Article.
 
Don't create articles at the top level of the Knowledge Base! This also makes it easier to ensure it is in the right category so that you do not have to move it later.

Once you are in the right section, you can use a premade article template from the Knowledge Base to structure your article effectively. There are two ways to access this template:

• See the Knowledge Base Article Template and copy/paste it into your article body.
• In the "Body" field of article creation, click Templates then DoIT Knowledge Base Template. 

Structuring and Formatting

This section focuses on how to structure and format the body of your article to ensure clarity and usability. Key elements to consider include using quick links and anchors to improve navigation, headings, and subheadings to organize content into clear sections, and text styles or bootstrap alerts to enhance readability and emphasize important points.

The body of your article should be comprehensive, detailed, and straightforward. Include all necessary information, such as relevant error messages, error codes, and specific resolution steps. By providing clear instructions, you make it easier for readers to resolve issues effectively. For example, if writing about Zoom issues, be sure to include any error codes related to the problem.

Text Styles

Text styles like bold, italic, and underlined text help emphasize key points and improve readability. Use these styles sparingly to highlight important information without overwhelming the article.

It is particularly recommended to use bold for button names or actions in instructions, helping users easily identify what to click. (Ex: Click Update Article to save changes.)

For accessibility, avoid using colored text to highlight content. Colorblind readers may struggle to distinguish certain colors, so rely on bold or italicized formatting instead. This ensures your article remains clear and inclusive for all audiences.

Bootstrap Alerts

To make important information stand out, consider using Bootstrap Alerts. These alerts help capture the reader's attention by differentiating key messages from the rest of the text. To add a Bootstrap alert, you'll need to use the Source editing mode rather than the standard editing page.

In the toolbar, click Source then paste the appropriate one of the following: 

<p class="alert alert-success">Success</p>

<p class="alert alert-info">Info</p>

<p class="alert alert-warning">Warning</p>

<p class="alert alert-danger">Danger</p>

Here is a preview of what those would look like:

Success

Info

Warning

Danger

Heading Structures

Organize your article into logical sections using headings. The headings available here are:

• Normal: the general body of the article. No font or color changes.
• Heading 1: Largest heading type. This one is not used as the title of the article (Subject) is already in this style.
• Heading 2: Used for major headings, like the "Structuring and Formatting" above.
• Heading 3: Used for subheadings, like the "Heading Structures" above.
• Heading 4 & below: Most other headings are not used but can be if your article finds it necessary.

To change the heading, highlight the text you want to change. In the toolbar click Normal then select the appropriate heading style.

Quick Links and Anchors

Another useful formatting feature is the ability to create anchors in the text, typically just before headers, which can help create a table of contents. This "Quick Links" section at the top of the page allows readers to quickly navigate long articles without having to scroll.

To create an anchor:

1. Place your cursor immediately before your header.
2. In the toolbar, click the Black flag icon.
3. Name your anchor (typically the section name) and click OK.
4. A red flag should appear next to your header. 
   

To turn the anchor into a Quick Link: 

1. Highlight the text you want to turn into a link. 
2. In the toolbar, click the Link icon. 
3. Select the Link to anchor in the text option under "Link Type". 
4. In the "By anchor name" dropdown, select your anchor and click OK.
5. Your highlighted text should now appear as a link.  
   
    

Supporting Media

Ensuring that your images and videos are accessible to all users, including those with vision and hearing impairments, is critical for meeting accessibility standards. All images must have alternative text (ALT text) to describe their content for visually impaired users. For videos, captions or transcripts are essential, as they make the content accessible to individuals who are hearing impaired.

Adding Images

Once you have your image downloaded to your computer, click the Image icon in the toolbar, then the Upload tab. Choose the image you want to use then click Send it to the Server.

You should then receive a pop-up that says "File uploaded successfully". The following window will then display the box for adding alternate text and changing the size dimensions of the image. 

It's essential that the Alternative Text accurately describes the image content. Avoid using generic terms like "Image of..." or "Screenshot of..." Please view the article on Accessible Images for an in-depth look at using alternative text on images. 

For accessibility on mobile devices, it’s recommended to keep image widths between 300-500 pixels. This ensures the images are displayed correctly across various screen sizes. However, if the image is wider than it is long, adjust the size accordingly.

Adding Videos

There are two ways to add videos to an article: Embedding a YouTube video or Embedding a Kaltura Video. 

Embedding a Kaltura Video

Using a Kaltura video allows you to keep the video stored locally, rather than being available on a public site like YouTube. You can find instructions for Uploading a Video to Kaltura, then follow the instructions for Getting an Embed Code for a Kaltura Video. 

Once you have your Embed link for your Kaltura video, click the YouTube icon on the toolbar. Paste the Kaltura Embed Code in the "Paste Embed Code Here" box and click OK.

Embedding a YouTube Video

To embed a YouTube video, click the YouTube icon on the toolbar. Copy the URL of the YouTube video you would like to use, then paste it into the "Paste YouTube Video URL" box and click OK.  

As long as captions are enabled on the original YouTube, viewers should have the option to turn it on when they begin to play the embedded video. 

See our example from the Chico State YouTube channel:

Tips & Tricks for Writing Articles

When writing your articles, keep the following key points in mind:

Spelling and Grammar

Ensure your article is free of spelling and grammatical errors. You can do this by using the built-in spell-check features or by using external tools, such as the Grammarly extension.  

You should also take the time to read through your article for proper punctuation and word usage. Having a team member review your article can help ensure you catch any mistakes you might have missed.

Style, Clarity, and Readability

To make sure your article is clear and understandable, you may want to reread and look over the article multiple times before submitting or publishing it. 

For general readability, it is also recommended that you:

• Aim for a professional, but approachable tone. Avoid being too casual.
• Refrain from using overly academic or technical language. 
• Use active voice whenever possible. For example, "Microsoft changed the rule" instead of "The rule was changed".
• Avoid long-winded, complex sentences. It is generally better to break things into short sentences or bulleted lists.
•  Use the University Writing Style Guide for proper usage of words, phrases, and capitalization of campus-related items.

Appropriateness for audience

Always keep your audience in mind when writing. The way you write an article on connecting to Eduroam should differ from how you write one about server upgrades.

For a general audience, such as students or staff, aim to use simple and clear language that anyone can understand. When writing for a more specialized audience (e.g., IT professionals), you can use more technical terminology.

Accessibility

In accordance with state and federal law, as well as California State University 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). 

For more information on making images and videos accessible, please see the "Supporting Media" section.

If you are trying to make certain text stand out or seem more important, try to stick to bold, italic, or underlined text. This is because changing font colors may not be legible for color-blind individuals. 

Copyright Issues

You may quote or link to content in your Knowledge Base article, but avoid directly copying and pasting material from other sites. It's recommended to limit the use of external content to a few paragraphs at most.

 Still need help? Contact IT Support Services for further assistance.
  
 Please do not leave the comment section blank! Provide constructive feedback to make this page better.