TABLE OF CONTENTS

• Writing guidelines
  • Keep articles focused on a single topic
  • Write complete, detailed content
  • Use real-world examples and scenarios
  • Use a clear and consistent structure
  • Explicitly state requirements, limitations, and availability
  • Choose the right content format
  • Provide text for all visual content
• Common writing patterns: good vs ineffective
  
  

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.

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

• Limit each article to one feature, workflow, or problem statement.
• Include links to related articles instead of embedding secondary workflows.
• Separate setup, usage, and troubleshooting into different articles when they serve different goals
• Clearly state when the information applies and when it does not

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

• Expand abbreviations and key terms explicitly
• Include both technical and non-technical explanations when relevant
• Provide answers that are understandable on their own, without relying on the user’s question or prior context.
• Use clear, specific, and action-oriented language, including precise UI labels and locations, rather than vague or promotional phrasing.

Examples

• Advanced Analytics is also referred to as Analytics Pro and AA Dashboard in the product UI and support conversations.
• SSO (Single Sign-On) allows users to log in using an external identity provider such as Google or Azure AD.
• Conversation assignment rules automatically route incoming tickets to agents based on conditions such as priority, channel, or customer type.
  
  

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

• Describe common user actions or workflows that lead to a feature or issue
• Explain when and why an error message appears, not just what it means
• Use consistent terminology throughout the article(for example, always “agent” instead of alternating with “support rep”)

Examples

• This error appears when a user enters an expired credit card.
• Users often see this message after attempting to log in from a new device.
• This issue occurs when the API token has expired.
  
  

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

• Use a single H1 to define the primary purpose of the article.
• Use H2 and H3 headings to separate tasks, options, or concepts.
• Break content into short, focused paragraphs.
• Use numbered lists for procedures or sequences that must be followed in order.
• Use bullet lists for features, conditions, or outcomes.
• Avoid long blocks of text or combining multiple steps into one paragraph.

Example

Reset a device (H1)

Follow these steps to reset your device.

• Press and hold the Power button for 10 seconds.
• Release the button when the LED blinks twice.
• Wait for the device to restart.
  
  

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

• State plan, role, region, and technical requirements clearly
• Call out unsupported actions using direct language
• Mention alternatives or supported paths when available
• Place this information before the step-by-step instructions

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:

• Surface short answers quickly when needed
• Cite detailed guidance when users need step-by-step help
• Always point to the most current and authoritative source

Best practices

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

 
Quick decision guide

• Solution article vs Q&A
  • 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.
• Solution article vs File
  • Use a Solution Article when content needs frequent updates.
  • Use a File when formatting must be preserved or offline access is required.
• When to use URLs
  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

• Describe what the visual shows and action the user should take.
• Use descriptive captions that explain the purpose of the image or video.
• Include clear, step-by-step text that mirrors the visual sequence.
• Reference UI labels, buttons, and menu paths exactly as they appear.
• Add meaningful alt text that explains the content, not just the presence of an image.
• Avoid using text such as, “See screenshot above” or arrows, highlights, and visual cues without explanation.
  
  

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.