Creating a Knowledge Base Article

All OITS staff can draft and submit new knowledge base (KB) articles for internal or public use. This guide will show you how to get started and what best practices to follow.

Table of Contents

• When to Create a Knowledge Base Article
• Starting a New Knowledge Base Article
• Body of the Article
• Tips for Writing the Article
• Images for the Article
• Table of Contents & Anchor Links
• Post-Editing Settings
• Submitting Your Article

When to Create a Knowledge Base Article

Consider creating a KB article for any of these situations:

• Any information that will have to be repeated more than twice. This includes common questions and requests from end users or ITS peers.
• Processes you expect or want end users to do themselves.
• Information related to a new system roll out.
• Answers or solutions to rare, but complicated issues which may only come up again after the original knowledge has been lost.
• When having a KB article link available will make your work easier.

Search the knowledge base before starting a new article, to be sure the topic hasn't already been covered.

Starting a New Knowledge Base Article

Go to the Knowledge Base website: https://services.tarleton.edu/TDClient/57/Portal/KB/

Be sure you are logged in. If not, click the Sign In link in the upper right corner of the webpage.

Click New Article.

Category:

• Click the search icon to pull up a list of all available categories.
• Select Public for articles intended for Tarleton faculty, staff, and/or students.
• Select Not Public for articles only intended for OITS staff.
• (Optional) Enter a keyword to include in the search.
• Click Search to narrow down the categories to Public or Not Public.
• Select the best matching category.

Order:

• Leave this at 1.0.
• Do NOT pin your article.

Subject:

• This is your article's title. It should use short, simple keywords and clearly define the point of the article.
• How To articles generally start with "How to [do X]"
• Browse existing KB articles to get a better sense of commonly used subjects.

Body:

• Click on Templates, then select ITS KB Template.
• Formatted text will now appear in the body. You will use this formatting throughout your article.
• In the next section, we will go over the elements found within the template.

Example of the ITS KB Template's HTML code:

<h4 class="alert alert-info" role="alert">Summary text here.</h4>

<h2>Table of Contents</h2>

<ul>
         <li><a href="#section1">Section 1 title here</a></li>
         <li><a href="#section2">Section 2 title here</a></li>
</ul>

<h2><a id="section1" name="section1"></a>Section 1 title here</h2>

<p>Section 1 text here.</p>

<h2><a id="section2" name="section2"></a>Section 2 title here</h2>

<p>Section 2 text here.</p>

<div class="alert alert-warning" role="alert"><span aria-hidden="true" aria-label="icon" contenteditable="false" role="region" tabindex="-1"><span class="fa fa-info-circle " style="color: rgb(0, 0, 0);"></span></span>Warning</div>

<div class="alert alert-danger" role="alert"><span aria-hidden="true" aria-label="icon" contenteditable="false" role="region" tabindex="-1"><span class="fa fa-warning " style="color: rgb(0, 0, 0);"></span></span>Danger</div>

Article Summary:

• Leave blank. You will do this at the start of the Body.

Tags:

• Tags are keywords used by the KB search engine.
• Enter any tags relevant to your article.
• Favor ones already in the system, but you can add new ones as needed.

Status:

• Set to Not Submitted for now.

Click Save.

A draft copy of your new KB article is now in the system, but only visible to you and KB administrators.

Body of the Article

Blue Section:

• Enter your summary text here. It should be short, no more than 2–3 sentences. Help the reader to be sure they are in the right place and tell them what the article will show/teach them.

Summary text here. Use paragraph format Heading 4

Section 1, Section 2, etc.:

• There are your major headers.
• Short articles can use only one header, or even none at all.
• Use headers to logically divide up your article.
  • One header for install, another header for settings.
  • One header for Mac instructions, another header for Windows instructions.
• Use anchor links and a table of contents, so the reader can skip right to where they need to go.
• You can copy/paste the Section and "Normal Text" lines to add additional headers.

Normal Text:

• This is for your main content for the related header.
• Avoid numbers for primary instructions, instead use line breaks.
• The top line after a line break should be normal text. But you can add bullet points under that for sub-steps.

Yellow Section:

• This formatting is for informational alerts for the reader (take note, be aware, etc.).
• Copy/paste the yellow box to make duplicates as necessary, and then change the text.

Red Section:

• This formatting is to give warnings to the reader (danger, do not do this, etc.).
• Again, copy/paste the original red box to make duplicates, and then change the text.

Tips for Writing the Article

Write for the lowest common denominator of your intended audience. Articles for end users need to be as simple and non-technical as possible. "How to" articles should be less explanation and more steps to follow. And make those steps easy to understand and follow.

• Be concise and simple.
• Don't explain "why" when you don't have to.
• Readers should be able to skim the steps at the top level. If more detail is required, use bullet points below the primary step.
• Avoid paragraphs as much as possible.
• Check your tone: be engaging and informative, not technical or confusing.
• Assume the reader does not have prior knowledge, this includes articles intended for fellow OITS staff.

The two biggest failings of a KB article are:

• It never gets written. Something is better than nothing.
• The author writes it from their knowledge level and skips details the reader needs to know.

Get feedback from a peer and see if the instructors are clear.

After publishing your first KB article, add "technical writing" to your resume.

Images for the Article

Take a screenshot for each step in a process.

• You may not use them all, but better to have them available.
• Avoid adding screenshots for common practices, such as logging in.
• Be sure to include screenshots that show proper settings, or can help the reader visually identify the next item they need to view or click.

Crop your images to focus attention where needed.

• Photos on Windows 11 and Preview on Mac are good enough for crop and annotation needs. Or you can move up to Adobe Photoshop if comfortable with that software.
• For entire websites, remove the top bars and blank bottom spaces.
• Draw highlights around important items in a screenshot (i.e. click this toggle right here).
• Crop out, black out, or otherwise hide any private information or personal identifiers.

Drag and drop your image onto an empty line break, typically just below related text.

• By default the image will be thumbnail size, but if the reader clicks on it, they'll get a full size version.

Right-click on your added image, select Image Properties. Add Alternative Text.

• Alternative Text can appear instead of your image for readers with visual impairments.
• The Alternative Text should describe the image, or relay the same important information via short text.
• This is required for new rules on accessibility of web content.

Save your images in a local folder along with your Word document draft. Keep everything until the KB has been approved and published.

Table of Contents & Anchor Links

KB article with multiple sections should include a Table of Contents near the top of the article, with anchor links to each listed section. This is especially helpful for readers when covering multiple conditions where they may only need specific sections (such as Windows vs Mac instructions, or desktop vs mobile).

Create a Table of Contents

Create the table of contents. between the summary and your first section. Wait until your KB draft is mostly done, so you know what the final layout will be and what sections to include.

"Table of Contents" should be in Header 2 format, same as any main section.

Add bullet points beneath "Table of Contents" and list each major section using the same section title.

See the table of contents. at the top of this article for an example.

Set Anchor Points

Set the blinking cursor to the left of the first section header.

In the menu at the top of the Body area, click on Anchor. It has a flag icon.

Enter the anchor's name.

• It should be a single word related to the section title.
• Each anchor must have a unique name.

A little red flag icon should appear where the cursor was, making your anchor point.

Repeat the step for each section header.

Link Anchors to the Table of Contents

Once all anchor points are set, go up to the table of contents..

Select (highlight) the first bullet point, then click on the Link icon in the top menu (two icons left of the anchor icon).

Set Link Type as "Link to anchor in the text."

Click Select an Anchor, and then select the matching anchor name.

Click OK. Repeat these steps for each item under the table of contents.

Test Anchors

Save your KB article (it can still be an unpublished draft).

Click on the article's link above the article's title, this will open a read only view of the article.

Click on each anchor link in the table of contents and confirm it scrolls to the correct section.

Post-Editing Settings

Before you can submit your finished article, you'll need to check and change some additional options. This includes cross-linking it to other related articles and uploading any needed attachments.

Be sure to click Save or Update Article before proceeding to other sections.

Near the top of the KB article, underneath the title, you'll find multiple tabs.

Settings

Click Settings.

Verify your Subject (aka title), Category, and Tags.

Change Owner to your group rather than your name.

1. Click on the Search icon, and then select "Groups" and click Search.
2. Browse or continue to search for your team's group. All OITS groups begin with "ITS Ticketing."

Changing the owner to your team will allow your team members to also see and edit the KB article. This helps prevent articles from going stale in the event the author changes positions or leaves Tarleton State.

Click Save.

Related Articles

Click the Related Articles tab.

Here you can add related KB articles to your new article.

• Linked articles will appear to the right of your article for the reader.
• Related articles must be already approved.
• By adding the article to yours, the system will automatically add your new article to the existing article, too.

Click the Add button.

Search for the other KB article by name or tags.

Once the correct article is listed, click Save.

Repeat for each related article you wish to add.

Related Services

Services are TeamDynamix (TDX) pages which document details on service catalog offerings aimed at end users. They are generally handled by the TDX admins. You may wish to connect your new KB article to a service if related.

Click the Related Services tab.

Click Add.

Search for the Related Service or Related Service Offerings to connect to.

Files

Click the Files tab.

Here you can add attachments to your KB article. The attachments will appear to the right of your article for the reader.

You can drag and drop attachments to the blue section (4 MB limit).

Or click Add and browse and upload the file (50 MB limit).

Submitting Your Article

After proofreading your article and perhaps having a peer review it as well, you can submit your article for publication.

If viewing your article in read mode, there will be a Submit button to the right. Click it.

If you are in edit mode, then follow these steps:

1. Click on the Settings tab underneath your KB article's title.
2. Change Status from Not Submitted to Submitted.
3. Click Save.

Notify your manager or designated TeamDynamix admin about your new article, including a link.

A TDX admin will review the article, make any necessary changes, and then publish it.

• While an article is "Submitted" anyone in OITS can find and view the article.
• Once "Approved" it will be visible to everyone, if using a Public category.

Expect to receive a review notification in one year to make sure your article is still relevant and up-to-date.