Writing Effective Knowledge Base Articles for CatBot

Quick Links: | CatBot Reading Process | Writing With CatBot in Mind | Avoid Common Misconceptions |

CatBot Reading Process

CatBot, the Division of IT’s support chatbot, uses GPT-4.1 to answer questions by pulling information from the Knowledge Base. Instead of showing full articles, CatBot breaks content into smaller, searchable chunks so it can deliver the most relevant part of an article to the user. This process makes it easier and faster for people to find solutions.

Behind the scenes, CatBot uses a structured workflow to process Knowledge Base articles:

• Article Discovery: CatBot crawls the entire knowledge base to find all available articles.
• Content Processing: It extracts and cleans article content while preserving important formatting.
• Metadata Enrichment: It adds structured details and links back to the original source.

For those who create Knowledge Base articles, understanding how CatBot works can help you write content that is easier to find and more useful. These same practices also improve the overall accessibility and readability of articles, whether someone is using CatBot or browsing the Knowledge Base directly.

Article Discovery

CatBot automatically scans the Knowledge Base once a week to collect all public, published articles. If an article is viewable without signing in, CatBot includes it. This weekly scan ensures that new content and recent updates are added quickly, so users always have access to the most current information.

Content Processing

When CatBot finds an article, it extracts the essentials: the title, body text, and any related services or request forms. Content marked with data-catbot-ignore="true" is excluded.

The text is converted into Markdown to keep it readable and consistent:

• Your article title becomes a top-level heading.
• Body headings become H2s.
• Links, lists, and semantic emphasis (e.g., bold, italics) are preserved. Empty sections and most visual styles are removed.

Important note: CatBot cannot see images or videos, only read the ALT text provided on images. If images include error messages, step-by-step visuals, or diagrams, that information is lost unless you describe it in alt text. Adding clear alt text ensures CatBot can understand and use the image content.

Next, the article is split into chunks at each heading. Each heading and its content becomes a standalone, searchable piece of text. Because CatBot may return only one section, every section should include enough context and instruction to be useful on its own.

Watch this short video to see how CatBot processes articles step by step:

Here is an example chunk from CatBot’s database, compared with the original article: Subscribing to Status Dashboard Notifications (technician access required; links to this specific revision).

Elements of this screenshot include:

1. The article title
2. The title of the section (in this case, an H3)
3. The content inside the section (simplified styling; semantic markup like bold is preserved)
4. Instructions telling CatBot how to cite the article
5. Extra metadata CatBot uses to track usage and provide richer responses

Metadata Enrichment

To make content easier to find and use, CatBot enriches each section with helpful context and instructions. Each section:

• Keeps the original article title for quick reference
• Maintains links back to the source material in TeamDynamix
• Preserves service request forms and related services so users can still take action
• Adds metadata to ensure users can always return to the full article if needed

After processing, the CatBot organizes all sections into a structured library of searchable documents. These are uploaded to Azure AI Search and become available to the live CatBot within a few hours of Article Discovery. 

Writing With CatBot in Mind

When writing Knowledge Base articles, remember that CatBot delivers content in small, searchable chunks. Each section should provide enough context to make sense on its own, since CatBot may display it without the rest of the article.

Reminder: All Knowledge Base articles must follow the University Style Guide: Web Writing Guidelines. 

Structure Your Content Effectively

CatBot splits articles at each heading but keeps the heading hierarchy for context. Make sure each section contains enough information to stand on its own. 

Plan your headings carefully, and avoid using too many nested headings (try to avoid anything below Heading 3). Group related information under logical headings. For step-by-step processes, keep all steps under one heading instead of splitting each into its own.

Consider how users will encounter your content, and include brief context at the start of major sections. You don't want someone to land on the Troubleshooting section before the Introduction section. 

Follow Good Writing Practices

Because CatBot may show sections out of context, clarity matters.

• Start with a concise introduction that explains who and what the article is about. 
• Use bold for interface elements rather than action verbs. For example, "Select Settings" instead of "Select settings."
• Use neutral verbs, like select or choose, instead of click or tap, unless it is a device-specific article. 
• Include screenshots where they add value, not for every step. Always provide alt text so CatBot and screen readers can convey the same information as the image.
• Avoid phrases like "see the section above" since users may not see or be provided context from other sections. 
• Links should be descriptive and tell the user where they go, so rather than "Click here to..." use "go to the Chico State Portal."

Optimize for Search

CatBot uses natural language and semantic search, so write clearly rather than stuffing keywords.

• Try to match content to how users actually ask questions. 
• Include error messages exactly as they appear. Users will often copy and paste error messages. 
• Use descriptive headings, without them being too long. For example, use "Reset Chico State Password" instead of "Reset Password" (too vague) or "How to Reset Your Password for Students, Faculty, and Staff" (too long). 

Avoid Common Misconceptions

Knowing what CatBot doesn’t do is just as important as knowing what it does. These common misconceptions can lead to unhelpful or poorly optimized articles:

• Tags and CatBot: CatBot does not use article tags in its search. However, tags are still valuable for regular Knowledge Base searches, so continue to use them appropriately.
• Don’t overuse keywords: CatBot understands meaning and context, not just repeated words. Use natural language and write clearly instead of repeating the same terms unnecessarily.
• Headings need context: CatBot sees the full heading path, so it understands where a section like Instructions fits. But for people browsing the Knowledge Base directly, headings should still be descriptive enough to stand on their own.
• Visual design isn’t preserved: Bold, italics, and headings remain, but complex layouts, colors, and styling are removed. Keep the structure clear and simple.
• Sequential reading isn’t guaranteed: Users may only see one section. Make sure each section provides complete, standalone information.

 Still need help? Contact IT Support Services for further assistance.
  
 Help us improve our Knowledge Base! Click Yes or No below, then let us know what worked — or what didn’t. Your feedback helps us improve our content and provide the best possible support.