Author Articles for CatBot

Learn how to write effective knowledge base articles optimized for CatBot by understanding how it processes articles in TeamDynamix.

Quick Links: | How CatBot Reads Articles | Writing With CatBot in Mind | Avoid Common Misconceptions |

CatBot, the Division of IT's support chatbot, uses GPT-4.1 to help users resolve IT issues by searching through Knowledge Base articles. When CatBot answers a question, it uses specific chunks from articles rather than entire documents. Understanding how CatBot ingests and presents your content helps you write more effective support documentation. These guidelines also represent general best practices for technical writing, making your content more accessible and useful for all readers, whether they access it through CatBot or browse the Knowledge Base directly.

How CatBot Reads Articles

CatBot's crawler processes the entire TeamDynamix knowledge base to make articles searchable and accessible to users. The system crawls through the knowledge base, extracts content from articles, and converts them into structured, searchable chunks. Understanding how CatBot works is helpful for authors who want to ensure their articles are effectively discoverable and useful to end users.

This short, visual explainer demonstrates the high-level process:

Key aspects of CatBot's processing workflow:

• Article Discovery: Systematically crawls the knowledge base to find all available articles
• Content Processing: Extracts and cleans article content while preserving important formatting
• Metadata Enrichment: Adds structured information and links back to original sources

To understand how CatBot processes Division of IT Knowledge Base articles, follow this technical overview:

Article Discovery

Once per week, CatBot's crawler recursively indexes all public knowledge base categories, gathering all public, published articles from the TeamDynamix Knowledge Base. Any article visible to an unauthenticated user is included in the crawl. This automated collection ensures that CatBot has access to the complete repository of IT documentation, including newly published articles and recent updates.

Content Processing

Once CatBot's crawler locates an article, it extracts the essential components that make up your content: the article's title and body text, along with any related services or request forms you've linked. Any content with a data-catbot-ignore="true" HTML attribute is also excluded from processing.

Next, the crawler transforms your rich text content into Markdown, a simple format that preserves most text formatting. Your article title becomes a top-level heading, while any headings you've used in the body text become H2s. Links, lists, emphasis, and other formatting elements are preserved, ensuring that the converted content maintains the same readability and organization as your original article. Empty sections and most visual styles are removed.

CatBot's crawler then segments your article into small, searchable sections (chunks) by splitting at every heading you've used, regardless of heading level. Each heading and its associated content becomes a standalone piece in CatBot's knowledge base. When users search for help, CatBot might receive just one section from your article, not the entire document. This means every section must make sense independently and contain enough context for users to understand and act on the information.

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

Elements of this screenshot:

1. The article title.
2. The title of the section. In this case, the original heading was an H3. 
3. The content inside the section. Note that visual formatting was stripped, but semantic markup like bold text remains.
4. Instructions telling the bot how to cite this article.
5. Extra metadata used by CatBot to track article usage and provide richer responses.

Metadata Enrichment

To enhance searchability and provide proper attribution, CatBot's crawler enriches each section with additional context and instructions for the bot. Every processed section includes the original article title for reference, maintains links back to the source material in TeamDynamix, and preserves any service request forms or related services you've included. This metadata ensures users can always find their way back to the complete article or take action through the appropriate service requests. 

Finally, CatBot's crawler organizes the processed sections into a structured library of searchable documents. These sections are uploaded to Azure AI Search and become available to the live CatBot within a few hours of processing.

Write With CatBot in Mind

Writing for CatBot requires thinking about how your content will be sectioned and presented to users seeking help. Since each heading creates a new searchable chunk, your writing strategy should balance comprehensive coverage with focused, self-contained sections that can stand alone when presented out of context.

Structure Your Content Effectively

When structuring your articles, remember that CatBot will chunk your content at every heading, but it maintains the full heading hierarchy within the chunk for context. This means you can use simple headings like "Instructions" or "Solution" because CatBot understands where they fit in your article's structure. However, each section should still contain enough information to be helpful on its own.

Plan your heading hierarchy thoughtfully. While CatBot can handle any depth of headings, excessive nesting creates fragmented content that may confuse users. Aim for a logical structure that groups related information together. If you're documenting a multi-step process that must be completed in sequence, keep all steps under a single heading rather than creating a new heading for each step.

Consider how users might encounter your content. CatBot might see just your "Troubleshooting" section without the introduction, or only the "Prerequisites" without the main instructions. Each section should provide value independently while contributing to the article's overall purpose. Include brief context at the beginning of major sections to orient users (and CatBot) who might land there directly.

Follow Good Writing Practices

Good technical writing practices are especially important when content might be read out of context. Start by being concise and detailed in your introduction, including key impacts and affected audiences. Use just enough detail—typically 3-5 sentences—for readers to evaluate whether the information applies to their situation.

Use bold to emphasize UI elements in instructions, not action verbs. For example, write "From the course sidebar, select Settings" rather than "Click the Settings button." This helps users scan for the interface elements they need to find. Always use platform-neutral language like "select" instead of platform-specific terms like "click" or "tap."

Include screenshots where they add value, but ensure they're properly annotated. For example, you can number interface elements in your screenshots and reference them in your text using [1], [2], etc. Always provide descriptive alt text for accessibility and because CatBot converts images to text during processing. Alt text should provide readers a similar experience to viewing the image.

Avoid self-referential language about the article itself outside of the article summary and introduction. Avoid "this article explains" or "in this guide, you'll learn." Instead, focus directly on the content. Similarly, avoid referencing other sections with phrases like "as mentioned above" or "see the previous section" since users might not have access to those sections.

When including links, always use descriptive link text that explains where the link goes. Never use generic phrases like "click here" or "this link." Screen reader users and anyone scanning the page should understand the link's destination from the link text alone. CatBot is also more likely to include links if it understands their destination. For example, write "review the campus password requirements" instead of "click here for password requirements."

For technical instructions, provide clear outcomes so users know when they've succeeded. End procedural sections by describing what users should see or what they've accomplished. Include what to do if something goes wrong, either within the section or by mentioning where to get help.

Optimize for Search

Making your content discoverable requires thoughtful use of language and terminology. CatBot uses GPT-4.1 for generating responses and Azure AI Search with both semantic and vector search capabilities. This means you don't need to stuff keywords unnaturally into your content. Instead, focus on aligning your content with user intentions and natural language queries.

Include error messages verbatim when documenting solutions to specific problems. Users often search by copying and pasting the exact error they see. Having the precise error text in your article helps CatBot match their query to your solution.

Write naturally rather than keyword stuffing. Remember that CatBot understands context and semantic meaning, so write naturally about your topic. The system can match user questions to your content even if they don't use the exact same words, as long as your writing clearly addresses the topic and user needs. The best optimization is writing content that genuinely answers user questions in language they understand.

Write descriptive headings that include keywords without being overly long. While CatBot maintains heading context, descriptive headings still help with search and navigation. Balance specificity with brevity—"Reset Your Chico State Password" is better than just "Password Reset" or "How to Reset Your Password for Students, Faculty, and Staff."

Avoid Common Misconceptions

Understanding what CatBot doesn't do is just as important as knowing what it does. Several misconceptions can lead to ineffective article optimization.

Article tags aren't used by CatBot. While TeamDynamix supports tagging articles, CatBot ignores these tags during processing and search. Don't rely on tags to make your content discoverable—focus on the article content itself.

Keyword density doesn't matter like traditional SEO. CatBot's GPT-4.1 and semantic search understand meaning and context, not just keyword frequency. Repeating keywords unnaturally won't improve searchability and may make your content less readable.

Generic headings work fine when appropriate. Since CatBot provides the full heading structure as context, a heading like "Instructions" under "Reset Your Password" > "For Students" makes perfect sense. You don't need to repeat context in every heading.

CatBot doesn't preserve your visual formatting. Most semantic formatting (bold, italics, headings, etc.) are preserved, but complex layouts, colors, or special formatting are stripped during Markdown conversion. Focus on clear, logical structure rather than visual design.

Sequential reading isn't guaranteed. Never assume users have read previous sections or will read subsequent ones. Each section must provide complete information for its specific topic.