Last updated: 2026-02-06

Source: https://support.freshdesk.com/support/solutions/articles/50000011859-write-freddy-ai-optimised-knowledge-content

Freddy AI uses your knowledge base as its primary source of truth. The clarity, structure, and completeness of your content directly affect the accuracy, relevance, and reliability of AI-generated responses.

Writing guidelines

Use the following guidelines to make your help content a reliable and accurate source of information for Freddy AI.

1. Keep articles focused on a single topic 2. Write complete, detailed content 3. Use real-world examples and scenarios 4. Use a clear and consistent structure 5. Explicitly state requirements, limitations, and availability 6. Choose the right content format 7. Provide text for all visual content

Keep articles focused on a single topic

Create solution articles that focus on a single topic, task, or issue, and clearly define when the information applies and when it does not.

Why is this important

When articles are focused, Freddy AI can surface precise answers and direct users to content relevant to their questions. Broad or multi-topic articles increase the risk of partial answers, incorrect assumptions, leading to misleading responses.

Best practices

Write complete, detailed content

Each solution article must explain the topic in detail, without relying on information from other articles or prior context.

Why is this important

Freddy AI retrieves and uses articles independently. If definitions or context are missing, Freddy AI may make assumptions or provide partial answers that do not fully address the user’s question.

Best practices

Examples

Use real-world examples and scenarios

When explaining features, behaviour, or errors, include real-world scenarios that reflect how users typically encounter them.

Why is this important Freddy AI relies on contextual details to match user questions to the right information. Real-world scenarios help Freddy AI recognise intent, especially when users describe problems in conversational or non-technical language.

Best practices

Examples

Use a clear and consistent structure

Structure solution articles using clear headings, logical sections, and well-organised lists so information is easy to follow and easy to interpret.

Why is this important Clear headings and hierarchy help Freddy AI identify the main topic, supporting details, and step-by-step instructions. When content lacks structure, Freddy AI may miss important context or present information out of order.

Best practices

Example

Reset a device (H1)

Follow these steps to reset your device.

Explicitly state requirements, limitations, and availability

Clearly explain when a feature is available, who can use it, and what it does not support.

Why is this important Freddy AI relies on explicit conditions to determine whether an answer applies to a user. If availability, requirements, or limitations are missing, it can lead to AI hallucinations and may suggest actions the user cannot perform.

Best practices

Examples

Availability: Pro and Enterprise plans only

Requirements: Admin or Analyst role required

Limitations: Historical data older than 365 days cannot be included in reports.

Choose the right content format

Use the most appropriate knowledge base format for each type of information so content stays accurate, easy to maintain, and easy for Freddy AI to surface in the right context.

Why is this important

Freddy AI can retrieve information from multiple knowledge base sources, but the quality of its responses depends on how well the content is structured and maintained. Using the right format helps Freddy AI provide concise answers, link users to the most relevant information, and avoid outdated or duplicated content.

When content is placed in the correct format, Freddy AI can:

Best practices

Use the following formats based on the nature of the content:

Quick decision guide

- Use a Solution Article if the content requires multiple sections, steps, or explanations. - Use a Q&A if the answer is short or likely to change often.

- Use a Solution Article when content needs frequent updates. - Use a File when formatting must be preserved or offline access is required.

Link to content that is owned, updated, or governed elsewhere—whether internal or external.

Provide text for all visual content

Any instructions presented in screenshots, images, or videos should also be explained clearly in text. Visual media should support written instructions, not replace them.

Why is this important

If key information exists only as videos or images, Freddy AI cannot reference or explain it when answering questions. Providing text descriptions ensures Freddy AI can accurately understand and relay the steps, options, or outcomes shown in the visual.

Text annotations also improve accessibility, ensuring users who rely on screen readers can access the same information.

Best practices

Examples

Screenshot description: The Reset device button appears under Settings > Device Management. Select the button and confirm to restart the device. Video summary:

This video shows how to enable email notifications by navigating to Settings → Notifications, turning on Email alerts, and saving the changes.

Common writing patterns: good vs ineffective

The following examples demonstrate how minor writing preferences can significantly affect Freddy AI's ability to accurately understand and reply to user questions. These examples do not introduce new guidelines. They illustrate common writing patterns that either help Freddy AI deliver accurate answers or lead to incomplete or misleading responses.