Quick Links: | Creating Articles | Reviewing and Updating Articles | Archiving Old Articles |
Before you begin...
Any TDNext user with editing permissions can create Knowledge Base articles. 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 (see below), fill out a request here: https://support.csuchico.edu/TDClient/1984/Portal/Requests/ServiceDet?ID=9668
Overview
If you are unsure who your department Knowledge Base reviewer is, please see here: https://support.csuchico.edu/TDClient/1984/Portal/KB/ArticleDet?ID=8533
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.
- 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 quickly locate relevant articles.
- 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 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
- 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.
Creating Articles
To begin creating your article, simply navigate to the category in the Knowledge Base where you want the article to appear, and click on the "New Article" button.
Tip: Make sure to navigate to the exact spot where you want the article to appear before clicking on "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.
Organization
This section is going to primarily cover the organization of the body of the article. The body should be thoroughly written, covering all necessary details, while also including error messages/codes, specific resolution steps, as well as any relevant links, videos, or images that support the article as a whole.
Formatting
Formatting an article will include the use of quick links, anchors, headings, subheadings, indents, text styles, and more. It is highly recommended to utilize headings and subheadings for organizing your main points. Similar to how you can see in this article, the main heading is "Creating Articles", then "Organization" as a subheading, then "Formatting" is a subheading after that. While you may not have as many sections as this article will have, it will help in various other articles if you can organize information into headings and subheadings.
Changing headings is easy. In the toolbar, click "Normal" (this is the default text format) and choose the appropriate text type. The headings are:
- Normal: the general body of the article. No font or color changes.
- Heading 1: Largest heading type. This one is not regularly used as the title of the article is already in this style.
- Heading 2: Used for major headings, like the "Creating Articles" above
- Heading 3: Most used for subheadings, like the "Organization" above
- Heading 4 & below: Most other headings are not used but can be if your article finds it necessary
One additional formatting feature that is offered is the ability to create anchors in the text (typically after headers) that can be linked at the top of a page to act as a table of contents. Adding a "quick links" spot at the top of your page allows for quick navigation of articles that are on the longer side. Instead of having to scroll through, the answer is quickly available.
To add an anchor, first click in the space immediately after your header; then in the toolbar, click the black flag icon. You will have to name your anchor, it should usually be the same as the header name. When you click ok, a little flag will appear after your section header.
Then to Quick Link your anchor, go to the space you want the link to be, highlight the word(s) that will be the link, and in the toolbar, click the link icon. Under "Link Type" select the anchor option, then from "By anchor name" choose the appropriate anchor from the dropdown menu. Hit ok, then your highlighted text should appear as a hyperlink. When you save the updates to the article, you should be able to test out the anchor.
Details
It is important to make sure that your articles are detailed and straightforward. By including specific steps to resolve a problem, you are making it easier for the reader to know exactly what they need to do to resolve the issue they are experiencing.
Another helpful piece to include would be any error messages or error codes that relate to a specific problem. For example, if you're writing an article about Zoom issues, you can put in the error code given for that problem. See the article Zoom Error 2116 - Your email is invalid. It quickly tells you that error code 2116 means there's an invalid email. The article then details the steps to resolve that problem.
Tips for writing Knowledge Base Articles
When writing your articles, also make sure to keep the following in mind:
- Spelling and grammar
- Style, clarity, and readability
- Appropriateness for audience
- Accessibility
- Copyright Issues
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 others to revise it.
If you are working in Firefox or Google Chrome, you can also install the Grammarly extension which will check spelling and grammar as you type. Often, it will offer suggestions for better phrasing too.
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. It is also recommended that a coworker reads it over to ensure someone other than the writer knows what is being discussed.
For general readability, it is also recommended that you:
- 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 (example: "The rule was changed." vs. "Microsoft changed the rule.")
- 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
Appropriateness for audience
When writing your article, one of the most important things to keep in mind is knowing your audience. This is essential to creating an article that is understandable and clear for the people using it. For example, you will write an article about Connecting to Eduroam differently than you would write an article about making server upgrades. The Eduroam article should be less technical and easier to understand for the general campus audience. However, the server upgrade article can use more complicated, technical language because the people reading it will know that kind of dialog.
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 "Using Images and Videos" below.
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
It is fine to quote or link content to your Knowledge Base article, but content should not be directly copied and pasted from another site. It is suggested to use no more than a couple of paragraphs from an external source in the Knowledge Base.
Using Images and Videos
Making sure that images and videos are accessible to both vision and hearing-impaired audiences is important for accessibility. All images must have alternative text (ALT text) that explains the content of the image to visually impaired users. Videos need to have captions or transcripts because videos tend to be inaccessible to the hearing impaired.
Images
Adding alternative text to images is quite simple. Once you have your image, click the image icon in the toolbar, then the "Upload" tab. You will choose the image you want to use, then "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 is NOT acceptable to put "Image" or "Photo" in the alternative text. As for size, it is recommended to generally keep the image width between 300-500 for the images to be more accessible on mobile devices. Of course, this may vary if the image is much wider than it is long, so please use your best judgment on those.
Videos
To embed a video, click the "YouTube" icon on the toolbar. Find the YouTube video you would like to use, and copy the URL. In the popup on the Knowledge Base, paste the copied URL in the second box. We do recommend unchecking the "Show suggested videos" box. You can also choose to have the video start at a specific time, just enter the start time in the last box on the page.
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:
This should cover many of the basics of creating new Knowledge Base articles. If you would like to utilize a premade template, please see ours here: https://support.csuchico.edu/TDClient/1984/Portal/KB/ArticleDet?ID=113453
Reviewing and Updating Articles
Knowledge Base articles should be reviewed at least once per year, if not more frequently. This is to ensure that articles are being kept up-to-date in terms of information, links, screenshots, and more. Checking the Knowledge Base regularly guarantees that staff, faculty, and students on campus are receiving the most up-to-date information, as well as making sure that articles that are no longer relevant or needed are being removed from the page.
Because everyone in your department needs to be able to review articles on or before the review date, you need to set the Owner of the article as your department, not leave it as you, an individual. This also allows other departments to know who to contact if there is an issue with the Knowledge Base article.
The easiest way to know that articles are being appropriately reviewed is by setting a review date on articles, and then moving the date once you have reviewed and updated the article. You should set a review date when you first create the article.
One place to look for information on what may need to be updated or fixed in the article is the Feedback portion at the bottom. Here, readers can choose to mark the article as "Helpful" or "Not Helpful" and can optionally leave comments for constructive feedback. Knowledge Base editors can use this user input to make the Knowledge Base better.
After reviewing articles, you can change the review date by clicking the "Edit Article" button on the right side, then under "Settings" changing the "Next Review Date". Make sure you save any changes
Archiving Old Articles
When reviewing articles, you may determine that the article is out-of-date or no longer necessary. In these circumstances, the article(s) can be removed from the Knowledge Base to avoid cluttering up pages and search results with incorrect information.
To archive an article, just click Edit then under Settings, change the status to "Archived". Archiving an article will also automatically unpublish it.
Please note that when you archive an article, it will still be viewable by you and any other KB Reviewers. It will appear with a yellow "Archived" tag when appearing in Search (see below). These articles will not be viewable to the public, so this is a good status to set articles you may want to reuse in the future.
If you do want to permanently remove an article that you are no longer using and is not relevant anymore, you can request to have the article fully removed. To do so, please fill out a request here with the title and link to the article(s) you wish to have removed: https://support.csuchico.edu/TDClient/1984/Portal/Requests/ServiceDet?ID=9580
You will also need to submit a claim to Google to have the article removed from Google Search results. Use the following link to do so: https://search.google.com/search-console/remove-outdated-content
Feedback
Please do not leave the comment section blank! Provide constructive feedback to make this page better. Further inquiries can be forwarded to ITSS in Meriam Library 142 or via phone at (530) 898-4357.