Writing Effective Zendesk Articles for AI

To effectively leverage Zendesk's native AI Auto Assist functionality, optimising your Help Centre knowledge base articles is crucial. Auto Assist, a component of Agent Copilot, relies heavily on your Help Centre content to generate accurate and helpful suggestions for agents. Think of your Help Centre as the "brain" for the AI agent; the more organised and refined it is, the smarter your AI will be.

This guide outlines best practices for structuring and writing Help Centre articles to ensure they are AI-ready, leading to improved automated responses and enhanced support efficiency.

In this article:

1. Understanding AI Auto Assist's Content Requirements
2. Foundational Principles for AI-Ready Content
3. Designing Articles for Effective Retrieval
4. Optimising Article Length and Readability
5. Language, Tone, and Localisation Best Practices
6. Continuous Improvement

Understanding AI Auto Assist's Content Requirements

AI Auto Assist uses a large language model (LLM) to understand ticket content and suggest replies or actions. It relies on your Help Centre as a context source for these responses, whether generating new text or suggesting relevant articles. To ensure its suggestions are accurate and relevant, your content needs to be specifically prepared for machine ingestion.

Back to Top

Foundational Principles for AI-Ready Content

These are the basic building blocks for optimising your articles:

• Prioritise Text Over Images and Videos:
  • Large Language Models (LLMs) are primarily text-based.
  • Images and videos provide minimal contextual information to AI unless accompanied by accessibility guidelines, such as ARIA labels and detailed descriptions. If visual aids are necessary, ensure they are thoroughly described in text.
• Structured Formatting:
  • Clear and Understanding Titles and Subheadings: Article titles and subheadings should be as clear and direct as possible. Titles should closely match how a customer might phrase their support request.
    • Examples: "Frequently Asked Questions about How to Write Zendesk Articles" is better than "Frequently Asked Questions". Both question formats ("How do I reset my password?") and simple, active phrases ("Resetting a password") are effective.
  • Utilise Bullet Points and Numbered Lists: These formats help AI understand steps and processes, making it easier to cross-reference information against user questions.
  • Consistent Formatting: Apply a consistent formatting style across all your content to help AI ingest information appropriately.
• Granular Content Segmentation:
  • One Topic Per Article: Keep each article focused on a single, specific topic. Avoid combining multiple, distinct issues (e.g., payment options and refund requests should be separate articles) or multi-step processes into one lengthy article. Providing too much irrelevant contextual information can confuse the AI.
  • Short Paragraphs: Use short paragraphs to allow the AI to extract direct, useful segments for response generation.
  • Organise with Categories and Sections: Group articles logically using categories and sections. Strive to keep sections to a maximum of 10 articles to improve the effectiveness of contextual retrieval.

Back to Top

Designing Articles for Effective Retrieval

To prevent AI "hallucinations" and ensure the most relevant information is surfaced:

• Keep Articles Unique: Avoid excessive overlapping terminology or steps across different articles, as this can cause the AI to pull information from irrelevant sources, leading to incorrect responses.
• Place Prerequisites at the Beginning: For long-form content, such as tutorials, provide prerequisite information or indicate multi-part series at the start of the article (e.g., "This is part two in a three-part series"). This helps the AI understand the broader context and may prompt it to reference linked previous articles for a better response.
• Address Common Product Names: If your product name is a common word (e.g., "Mech Assist," where "assist" is common), try to avoid using that word or its synonyms for other purposes in your articles. If unavoidable, provide explicit definitions for product jargon (e.g., "Mech Assist is our co-pilot solution") to prevent the AI from confusing it with its generic meaning.
• Centralise FAQs: Instead of including small FAQ sections at the bottom of individual articles, compile frequently asked questions into one dedicated FAQ article per section. This allows the FAQ article to be pulled as a primary context source, especially beneficial with larger AI model token windows.
• Leverage Article Labels:
  • Enhance Contextual Retrieval: Labels significantly improve the contextual retrieval process.
  • User Search Integration: Utilise tools like Google Analytics to identify common user search terms and add these as labels to relevant articles. This benefits both human search and machine retrieval.
  • Filtering Results: Labels can be used in "autoreply with articles" triggers to filter results, helping to reduce "noise" in your Help Centre or to target specific customer segments (e.g., Ford vs. Toyota content). Note that labels increase the weight of the search algorithm, directly impacting search effectiveness.

Back to Top

Optimising Article Length and Readability

The quantity and complexity of text directly impact AI performance:

• Optimal Article Length: Aim for articles that are between 350 to 450 words in length.
  • Articles under 100 words significantly increase the likelihood of AI hallucinations.
  • Articles over 500 words can lead to AI confusion and a higher abandonment rate by human users.
• Avoid Complex Tables: AI often struggles with complex tables and may hallucinate. Simple tables with Boolean values are generally acceptable. For more intricate data, consider:
  • Using accessibility guidelines (e.g., ARIA column/table descriptions) if your tool supports it.
  • Providing a descriptive overview of the table's purpose and content in plain text.
• Use Clear Transitions: If not using numbered lists, incorporate transitional statements (e.g., "Next, you will go to the Account Settings Page") to guide the AI through different parts of a topic.
• Designate Optional Information: Create an "Additional Information" section at the end of an article for optional content. This signals to the AI that this information may be relevant in certain situations, but is not always necessary for primary response generation.

Back to Top

Language, Tone, and Localisation Best Practices

The nuances of language are critical for AI understanding and a consistent brand voice:

• Consistent Terminology: Continuously and consistently use preferred terminology throughout your Help Centre. This is the most effective way to "train" the AI to use your specific phrasing without fine-tuning. Vendors may be able to adjust "logit bias" for key terms.
• Explicit Product Jargon Definitions: Provide short, explicit definitions for all product-specific jargon (e.g., "Zendesk Explore is our reporting offering"). This prevents the AI from using incorrect synonyms.
• Provide Example Scenarios: For complex areas of your product, include example scenarios to help the AI understand the nuances of when to use specific information.
• Aim for a Seventh-Grade Reading Level: Write articles using direct and simple language, targeting a seventh-grade reading level. This readability level benefits both AI understanding and human users. Tools like Kincaid can help assess this.
• Avoid "Contact Support" Instructions: Never include phrases like "contact support" or "reach out to support" as a step in your articles, especially if the user is interacting with an AI chatbot. This creates a jarring experience as the user is already engaged with support.
  • Instead, remove the step entirely or rephrase it to ask for specific information that support would need (e.g., "If this article hasn't resolved your issue, support will ask for X, Y, and Z information"). This helps the bot understand it needs to gather information rather than handing off.
• Maintain an English Local: Regardless of your primary customer base, you must keep an English local version of your Help Centre up to date. Most major AI models are trained on English content, and their tokenisation and translation processes are built upon this. Ensure a one-to-one correspondence between your primary language content and the English version.
• Avoid Slang, Idioms, and Unexplained Acronyms: Unless specifically defined or widely understood, avoid using slang, idioms, and industry-specific acronyms. Spell out acronyms. If slang is integral to your brand's voice, ensure the model is trained to understand and use it correctly, potentially through fine-tuning or by providing contextual descriptions.
• Ensure Appropriate Formality and Tone: The tone and style of your articles will directly influence the tone of AI-generated responses. Aim for a consistent and appropriate tone across all content. A "dry," plain text basis is generally easier for AI to work with, as it's more challenging for AI to adjust from overly friendly or informal content to a business-like tone.
• Handle Hardcoded HTML/JavaScript: AI will typically strip out HTML and JavaScript elements, processing only the plain text. If content relies heavily on these elements to make sense, consider creating a separate, simplified article specifically for bot ingestion, distinct from the customer-facing version.

Back to Top

Continuous Improvement

Launching your AI agent is just the first step; ongoing monitoring and refinement are essential for long-term success.

• Monitor Performance: Regularly check your insights dashboard for key metrics like resolution rate, handoff rate, and conversation volume. Review conversation transcripts to see how customers interact with your AI.
• Iterative Content Improvement: Unresolved chats or instances where the AI struggles with certain topics often indicate gaps, unclear information, or incompleteness in your Help Centre articles. Use this data to update, add, or reorganise content, ensuring your AI remains accurate and helpful.
• AI is Content-Driven: Remember that the effectiveness of your AI is directly proportional to the quality and structure of your Help Centre content. A strong Help Centre underpins a stronger AI.

Back to Top

By following these best practices, you can create a robust and AI-optimised Zendesk Help Centre that empowers Auto Assist to provide accurate, relevant, and helpful suggestions, ultimately enhancing your support operations.