Knowledge Base Authoring Guide for Fraser: the IT Support Bot

The bot can search through all "public" knowledge base articles and services in the IT Services TeamDynamix applications.

The bot uses a hybrid search approach via an Azure AI search service that combines two methods:

• Keyword Search (BM25): Matches exact words and phrases in your content
• Semantic Search (Vector/AI): Understands meaning and finds conceptually related content

Both methods work together, so articles that excel at both will rank highest.

The title (aka subject) is one of the most heavily weighted fields in search.

Do:

• Use clear, descriptive titles that state the topic directly.
• Include the primary keywords users would search for.
• Keep titles concise but complete (5-15 words is ideal).

Don't:

• Use vague titles like "Information" or "Instructions"
• Use internal jargon or acronyms without explanation
• Start titles with "How to" for every article (vary the phrasing)

Good Examples:

"Reset Your UFV Password Using Self-Service"

"Connect to UFV WiFi using Eduroam"

"Request New Software Installation for Lab Computers"

"Troubleshoot Brightspace Assignment Submission Issues"

Poor Examples:

"Password" (too vague)

"WiFi Setup" (missing key details)

"SCCM Software Request Process" (jargon-heavy)

The summary appears in search results and helps the AI understand what the article covers. 

Do:

• Write 1-3 sentences summarizing the article's purpose
• Include the main problem and solution type
• Mention key systems, tools, or user types involved

Good example of a Summary:

"Step-by-step instructions for students and staff to reset their UFV password using the self-service portal. Covers both 'forgot password' scenarios and other possible password issues."

Don't:

• Leave the summary blank (falls back to title, reducing search quality)
• Copy-paste the first paragraph of the body
• Use generic text like "This article explains..."

The body content is converted from HTML to plain text (Markdown) and then chunked for search.

Well-structured content searches much better.

Break content into logical sections with headings.

The bot can better understand and cite specific parts of your article.

## What is x (your topic)

A brief summary of what x is and what it does.

## Before You Start
Prerequisites and requirements...

## Step-by-Step Instructions
1. First step...
2. Second step...

## Troubleshooting
Common issues and solutions...

Numbered steps are easier for the chatbot to extract and present to users.

1. Navigate to https://identity.ufv.ca/mfa_reset
2. Enter your 9 digit student ID
3. Click submit
4. ... more instructions here

If users might encounter specific error messages, include the exact text in your article.

This dramatically improves search accuracy when users paste errors.

## Common Errors

**Your session has expired**
This error appears when... To fix it:
1. Clear your browser cache
2. Log in again

**Account locked**
Your account locks after...

Write as if explaining to a user directly.

The semantic search understands natural language better than technical shorthand.

Good:

"If you can't connect to the WiFi network, first check that you're selecting EDUROAM rather than UFV-GUEST or one of our other networks."

Less Effective:

"Connection failure: verify SSID = EDUROAM"

Always spell out acronyms on first use.

Users may search for either form.

The Learning Management System (LMS), also known as Brightspace or MyClass, is where...

Users describe problems in different ways.

Include common variations:

## Reset Your Password (Change Password, Forgot Password)

If you've forgotten your password, or need to update your password...

Tags supplement search but are not as important as good title, summary, and body content.

Use tags to add:

• Alternate terms users might search for
• System names and acronyms
• User types (students, staff, faculty)

Example Tags:

• password, reset, forgot, myaccount, students, staff

Audience Tags (important for Personalized Search)

Help identify and target different user groups for personalized communication or experiences.

The bot uses audience-based scoring profiles to personalize search results for authenticated users:

• Students (logged in with @student.ufv.ca) see articles tagged with students ranked higher
• Employees (logged in with @ufv.ca) see articles tagged with staff, or faculty ranked higher
• Anonymous users see neutral ranking (no audience preference)

How it works:

Tag matches get a 2.0x boost in search ranking

Best Practice: Always tag articles with their intended audience:

• Use student for student-focused content (enrollment, tuition, student services)
• Use staff, or faculty for employee-focused content (HR, payroll, internal systems)
• Use multiple tags if content applies to multiple audiences
• If content is universal, you can omit audience tags (neutral ranking for all users)

Example Audience Tagging:

Article: "Register for Classes in MyUFV"
Tags: student, registration, classes, enrollment

Article: "Submit Expense Claims in Chrome River"
Tags: staff, faculty, expenses, chrome-river, reimbursement

Article: "Connect to WiFi"
Tags: wifi, wireless, network, student, staff, faculty  (universal content)

Categories help with organization but are less important for search than content quality.

Use consistent category names across related articles.

Service catalog items follow similar structure rules.

Key fields are listed below.

Name

High value for bot search.

Best Practice:
Use clear, action-oriented (e.g., "Request Software Installation")

Short Description

High value for bot search.

Best Practice:
1-2 sentence summary of the service

Long Description

High value for bot search.

Best Practice:
Full details, eligibility, process steps

Tags

Medium value for bot search.

Best Practice:
Alternate terms and keywords

Category

Low value for bot search.

Best Practice:
Organizational grouping

Structure articles around the user's problem:

## Overview
Brief description of the issue and who it affects.

## Symptoms
What the user experiences (error messages, behaviors).

## Cause
Why this happens (optional but helpful).

## Resolution
Step-by-step fix.

## Prevention
How to avoid this in the future (optional).

For complex topics, include an FAQ:

## Frequently Asked Questions

**Q: Can I use this on my personal device?**
A: Yes, follow the same steps using your UFV credentials.

**Q: What if I don't receive the verification email?**
A: Check your spam folder. If not there, wait 5 minutes and try again.

When procedures differ by platform, use clear sections:

## Windows Instructions
1. Step for Windows...

## Mac Instructions
1. Step for Mac...

## Mobile (iOS/Android)
1. Step for mobile...

The bot cannot read text in images.

If step-by-step screen shots contain important information, include that text in the article body.

Try not to:

Only use an image showing a dialog box with button labels

Instead, try to: 

Use an image plus text like:

"Click the 'Advanced Settings' button in the lower-right corner"

Technically accurate content that is not understandable to the user is not useful.

For example:

"Configure FLUX CAPACITOR attributes via smorg policy: ensure EAP-TLS with certificate chain validation against AD-CS root CA."

Rewrite content so it is readable for your audience:

"The WiFi authentication uses your UFV account credentials. If you see certificate errors, your device may not trust UFV's security certificate. To fix this..."

The bot presents whatever content is published.

Outdated articles can give users wrong information.

Keep a regular review schedule.

Your article body is split into chunks (approximately 2000 characters each) for indexing.

This means the bot will receive "chunks" of your articles as search results, not the whole thing.

This prevents the bot from getting confused when a article is returned that has 10,000 characters, but only 1,000 characters are relevant to the user's query.

Practice content clarity

Self-contained sections work best:

• Each major section should make sense on its own.

Don't bury the answer:

• Put the key solution early in each section.

Repeat context when needed:

• If a section might be shown alone, include enough context.

Good Example: 

Each troubleshooting item includes enough context to be useful standalone.

## WiFi Won't Connect After Password Change

After changing your UFV password, you may need to update saved WiFi credentials:

1. Forget the UFV-SECURE network
2. Reconnect and enter your new password

Poor Example: 

Context only at the beginning, with steps that reference it.

## Introduction

This article covers various WiFi issues...

## Issue 3

For this issue, do the following:
1. Click the button mentioned above

Before finalizing an article, run through this checklist:

 Title is descriptive and contains primary search terms

 Summary is filled out with 1-3 meaningful sentences

 Body uses headings to organize content

 Steps are numbered and clear

 Error messages are quoted exactly as users see them

 Acronyms are defined on first use

 Images have text descriptions of important elements

 Tags include alternate terms users might search

 Content is current and accurate

How the bot pipeline works:

1. Nightly Sync: All KB articles and services are synced from TDX to Cosmos DB at 1:00 AM UTC

2. HTML to Markdown: Article HTML is converted to clean Markdown (base64 images removed)

3. Embedding Generation: Content is vectorized using OpenAI's text-embedding-3-large model (3072 dimensions)

4. Hybrid Search: User queries are matched using both keyword (BM25) and vector similarity

5. Query Reformulation: User questions are reformulated into 2-8 word search phrases for better matching

6. Result Ranking: Top 5 results are presented to the AI with relevance scores

Fields Used in Search Index