Contributing to the Knowledge Base

Before you start to write your article, it’s important to understand what purpose it will serve and how it will fit with existing resources. Consider the following questions:

1. What resources are already available?
   • Every KB article about a topic needs to be able to both stand alone and fit with the rest of the topic’s available resources (if any). A good place to start is to search the Knowledge Base and see what resources already exist relating to your topic.
   • If you find that there’s an existing article about exactly what you were planning to contribute that just needs a small addition or improvement to fit the gap you’ve identified, you’re encouraged to report a problem (see below) with that article and suggest your addition/improvement that way rather than adding a completely new article.
   • If there isn’t a perfect match for your intended topic, reviewing the existing related articles will likely help you to nail down exactly what gap in knowledge you’re filling and avoid duplication.
2. Who is this for? (Audience and intended user)
   • All articles found at kb.bcit.ca have one of two identified audiences: Students or Faculty and Staff and this is part of the article’s metadata (see below).
   • The intended user of your resource is likely to be more granular and specific than its broad audience. For example: students connecting to wireless for the first time, faculty submitting grades at the end of a course, etc.
   • Understanding who your audience and user are can give you insight into the kinds of information they are likely to need in the article.
3. When would this resource be used (and how often)?
   • The majority of resources in the Knowledge Base are of the “just in time” variety. We would expect that a user would seek them out (or be directed to them) when they have an unfamiliar task to perform or a problem to solve.
   • Understanding what situation or circumstance is likely to have prompted a user to seek out the article you’re writing can help you determine where in the process to start your instructions, how much context to provide, and so on. It can also help you to recognize whether the article is actually necessary or useful.
   • Understanding how often a resource would likely be used can help you gauge the level of effort and detail to incorporate in your article.
4. How much could the user of this resource be expected to know before they arrive at the resource?
   • In order to be in the position of needing your resource, how much knowledge and experience would the user already have?
   • Understanding this helps you to pitch your instructions at the correct level for the user. Some systems are complex, but the only users who would be using them could be expected to have a certain base level of knowledge, so you don’t need to provide as much introductory or basic information to assist them. Some systems are accessed by users with a much broader variety of ability, so you’d want to ensure that even beginners could make use of the information you provide.

Articles are generally one of the following types. The information you gathered in step 1 (see above) should make choosing an article type relatively simple.

How to

• Contain step-by-step instructions for completing a task (or closely related set of tasks).
• Most articles in the Knowledge Base are of this type.
• Examples:
  • Logging In to AppsAnywhere For the First Time
  • Creating a New Page in Public Website WordPress
  • Updating Saved Logins in Browsers and Password Managers

Overview/about

• Provide an introductory description of a technology/system that can serve as a basis for understanding other articles.
• Do not contain any how-to instructions.
• Link to all other articles related to that topic and serve as a landing page for the topic.
• Examples:
  • About AppsAnywhere
  • About Public Website WordPress

Quick reference

• Provide a collection of useful related information about a topic or in support of a process
• Sometimes (but not always) in the form of a “Frequently Asked Questions” list
  • Examples:
    • Logging in to BCIT Tools and Systems (Students)
    • Frequently Asked Questions about Multi Factor Authentication Using Duo
    • Zoom Privacy and Security Etiquette at BCIT
    • Glossary of Common Terms

Known problem

• Describe a known problem and prescribe a solution or workaround.
• Example:
  • Problem with Duplicate/Clone Display Projector Output on Windows 10 Laptop

Video

• May contain a mix of different types of content in video form.
• Example:
  • About AppsAnywhere

Every article/resource in the knowledge base needs to have the following associated metadata elements:

Content owner

• Every article has an assigned Content Owner. This is the IT Services employee responsible for ensuring that the article remains accurate and relevant over time.
• The Content Owner is often the original creator of the article, but not always (it’s not uncommon write an article and turn it over to a colleague for maintenance). When a Content Owner changes role or leaves BCIT, the Knowledge Manager works with the Content Owner and their manager to find a replacement.
• If you are not a member of the IT Services department, you will need to partner with one in order to contribute to the Knowledge Base.

Subject matter expert

• A Subject Matter Expert (SME) is a person with specialist knowledge of the topic of the article who can be consulted about the article if necessary. In some cases, the original creator of an article may turn over Ownership to a colleague but still be listed as the SME. As well, if a Content Owner is expecting to leave the institute for whatever reason, they could ensure that the next planned Content Owner is listed as the SME.
• Contributors from outside IT Services who are partnering with a Content Owner to create and maintain a resource are usually listed as SMEs.

Review cycle

• The Review Cycle is how often the article will be reviewed to ensure that it is still current, accurate, and relevant to our users.
• All articles must be reviewed at least yearly, with most Review Cycles in the three-to-six-month range.
• Articles can also be set to be reviewed on specific dates each year, if the topic they cover is likewise tied to specific dates. For example, the article for students about accessing their T2202A form is set to be reviewed in January of each year to ensure it’s accurate and current when students use in the coming income tax season.
• A recommended default Review Cycle is: first review three months after the article is first published, then every nine months thereafter.

Audience

• All articles found at kb.bcit.ca have one of two identified audiences: Students or Faculty and Staff.
• Articles for the Students audience have “kb.bcit.ca/student/” at the start of their URL. Articles for Faculty and Staff have “kb.bcit.ca/faculty-staff/” at the start of their URL.
• The audience for an article determines which search results the article will appear in. Searching the Knowledge Base with the “Student Resources” filter only returns articles for the Student audience, whereas searching with the “Faculty and Staff Resources” returns all articles (both for the Student audience and the Faculty and Staff audience).
  
• Articles for the Students audience may occasionally include information marked in the text as being for faculty and staff – if a shared process would need only be a slight variation of the student instructions for faculty and staff – though this should usually be avoided. However, articles for the Faculty and Staff audience never include information intended specifically for students as students could not be expected to find them.

Knowledge Base category/ies and tag/s

• These taxonomies help to organize and show relationships between articles. The Knowledge Manager can assist you to determine what categories and tags should be used for the article once you’ve submitted it.
• Most articles include a dynamic list of related articles that a user may be interested in viewing next, and this list is generated via the use of these Categories and Tags.

Knowledge Base article ID number

• This is a unique identifier for your article that persists for the entire life of that article.
• It is automatically generated when you request an article (see below) (you don’t need to determine it for yourself in advance, the KB team will take care of it for you).
• This KB Article ID number is associated with the article record in Cherwell, which is where the other elements below are recorded and tracked.

If you’ve spent the time to prepare using the guidelines above, writing your article should be a little easier than it would otherwise be. Still, writing something for pubic consumption is a bit intimidating for many. As all submissions are at least lightly edited for consistent style and tone, as well as conformity with the BCIT Writing Style Guide, your submitted article does not need to be perfectly written. The Knowledge Base team will fix typos and punctuation errors and smooth out awkward phrasing as needed, as well as ensuring that . The most important thing, and the value that only you can provide, is information that is as accurate and complete as you can make it.

Tips

• Don’t let perfect be the enemy of the good. Not only will your submission be at least lightly edited before publishing, you can always improve or add to your article in the future, after it has been published the first time.
• A second set of eyes can catch what you miss. For example, for How To articles, once you’ve written the steps out, have a colleague attempt to follow them and tell you if you’ve missed a step somewhere along the way (this is very easy to do if you’re too familiar with the process you’re documenting).
• When providing screenshots, it helps if you include more of the screen than you think you need. The Knowledge Base team will further crop screenshots and optimize the images as needed.
• Avoid uncommon acronyms/jargon where possible. Spell out acronyms if they’re unlikely to be well-known.

Guidelines

Article title

Unique, identifiable, and descriptive, the title should be able to stand alone and make clear what the user will find within it.

The various article types use different naming conventions:

• How To: Article title specifically describes the task that will be explained, includes the most likely keywords that a user would search for, and does not include the words “how to”. Start these titles with the gerund form of a verb (meaning it has -ing at the end of the word) – for example: “Accessing”, “Installing”, “Updating”, etc.
• Overview: Article title is the word “About” followed by the broad topic that it covers.
  • Note: Because the dynamic lists of related KB articles at the bottom of each article are always in alphabetical order, naming Overview articles with “About” ensures that the Overview article will, in almost all cases, naturally appear at the top of the list.
• Quick Reference: As these articles have a lot of variety, article titles are also quite varied. In general, except for rare exceptions, article titles would not usually resemble how to, overview, or problem titles. Include the word/phrase that best describes the thing the article has collected multiple of – for example: “Resources”, “Definitions”, “Frequently Asked Questions”, etc.
• Known Problem: Article title describes the problem with the tool/system/task that the article will solve. Start these titles with the word “Problem” or “Problems”
• Video: Article title would follow the pattern that best fits the content it contains and conclude with “(Video)”.

Remember:

• A good article title not only makes clear that an article is the right one for the person seeking it, but also makes it obvious when it’s the wrong one.

Introduction

Every article needs a short orienting paragraph or two that tells the reader what this article is going to be about. If it’s a How To article, the introduction should include some indication of when a user would need to use the provided instruction (a use case).

Main content

The main content of your article will take a different form depending on the article type. Try to follow these general recommendations:

• Prioritize readability and conciseness. Write primarily in short, uncomplicated phrases and sentences and using a more limited vocabulary than you might use in conversation or other types of writing.
• Don’t make your reader work any harder than they need to. If your article solves a problem, your intended readers are necessarily people in the middle of experiencing a problem and may be reading your article in a moment of stress or frustration. Try to always take your readers on the shortest or easiest path to the solution, avoiding the potential for confusion or missteps where possible.
• Try to take a generally positive and encouraging tone. For the most part, focus on what the user can and should do rather than on what they can’t or shouldn’t. If you do need to mention a prohibition or limitation, be matter-of-fact rather than punitive.

The various article types also follow different general outlines, though Overview, Quick Reference, and Video are flexible. Two types are more rigid, however:

• How To
  • If there is more than one procedure in your article, start each one with a heading that very briefly describes the procedure (“Logging in to…”, “Modifying your preferences…”, etc.).
  • If there are more than two or three procedures, they may be displayed using an Accordion (“click-to-expand” content, like the information you’re currently reading).
  • For each procedure, write each step as an item in a numbered list, after a short contextual phrase. For example:”In your web browser:
    1. Go to…
    2. Click on…”
  • Finish the steps with a description of the end result so that the user can confirm they were successful.
• Known Problem
  • Starts with a heading – “Problem” – followed by a clear but concise description of the problem, including the text of any error messages.
  • The second section is the solution or workaround section and starts with a heading indicating which is being provided (“Solution”, “Workaround”). If there are steps to follow, they should be formatted in the same way as they would be in a How To article. Otherwise, they can be in the form of a paragraph.