Best Practices for AI

Ready Knowledge Documents

Download PDF

Best Practices for AI-Ready Knowledge Documents

Do’s

1. Use Clear, Simple Language

AI performs better when it can easily analyze information, be thorough but concise.

2. Structure Content Logically

Use headings, subheadings, bullet points, and numbered steps and break down processes into clear, step-by-step instructions - use consistent formatting for FAQs, How-Tos, Troubleshooting guides, etc.

3. Label Content Clearly

Use descriptive titles and metadata (tags & categories) so AI and search tools can surface the right info. For example: “How to Reset Your Password using a Mac device” is better than “Password Help”.

4. Keep It Focused

Each article should cover a single topic or task. One article = one question answered or one process explained in thoughtful detail.

5. Include Context and Outcomes

Explain why the task is done, not just how. Include possible error messages and what to do if something doesn’t work.

6. Use Consistent Terminology

Regulate terms consistently throughout the article. For example: always say “service request,” not sometimes “ticket” and sometimes “incident” when referring to the specific issue. Create and follow a style guide for terminology and formatting.

7. Keep It Up to Date

Include version numbers, last updated dates, and ownership info. Set review reminders—stale content is a major AI risk and could lead to improper data generation.

8. Add Keywords Naturally

Think of the words users will search (and how AI will interpret the query). For example: Include terms like “forgot password,” “can’t log in,” and “password reset” in the same document .

9. Link Related Articles

Help AI and users navigate to additional relevant context. Example: “For MFA setup, see [Enabling Multi Factor Authentication].”

10. Use Structured Fields Where Possible

When creating knowledge articles, some platforms let you enter content into specific labeled fields rather than just one big text box. Think of it like filling out a form instead of writing an essay—the AI knows exactly where to find each type of information. Examples of structured fields include: Symptoms – What the user experiences (e.g., "Outlook shows 'Disconnected' message") Cause – Why it’s happening (e.g., "Expired password after policy update")

Resolution – The exact steps to fix it Applies to – What systems, devices, or roles this article is relevant for (e.g., "Windows 11, Outlook 365")

11. Let AI Be Your Guide to Updating Content Stay current and revisit content often. Let AI’s knowledge metrics streamline updates with precision.

Dont’s

1. Don’t Upload PDFs or Scanned Docs as Primary Content These are hard for AI to scan accurately, especially if they're image-based or poorly structured.

2. Don’t Dump Ticket Data into the Knowledge Base

Ticket resolutions lack context, structure, and consistency. While some companies/employees are thorough, it depends on the person and situation and can lead to inconsistent data. AI trained on unstructured ticket logs may generate incorrect or irrelevant answers.

3. Avoid Overloading a Single Document

Long, unfocused documents covering multiple topics confuse both AI and humans alike. Stay hyper focused on one solution at a time for each article to generate better results. Split long articles into modular, task-specific chunks.

4. Don’t Use Vague Titles

BAD - “Connection Issue Fix”.

GOOD - “How to Fix VPN Connection Issues on Mac”

5. Don’t Assume Reader Knowledge

AI (and even some user) won’t “just know” internal acronyms, terms, or shortcuts. Be thorough in descriptions and clearly define terms and acronyms if it is vital that they be included in the document.

6. Don’t Use Inconsistent Formatting

Fluctuating styles and layouts reduce AI’s ability to identify intent and context. Create a template that consistently works to aide the AI’s interpretation.

7. Avoid Outdated, Unsupported, or Unverified Info

AI doesn’t know if a document is obsolete unless it’s marked clearly. Be active in curating content so it is up to date by using “Outtaded” labels or archive old content visibly.

8. Don’t Rely on Images Without Descriptions

AI can't interpret images, diagrams, or highlights unless accompanied by text or alt-text. Include captions or explanatory context. Note: highlights do NOT help AI interpret importance.

Example:

Figure 1: Settings > Display. Toggle "Dark Mode" ON

9. Don’t forget to think like AI

Write KM content as if you’re answering a user query directly.

For Example:

User query: “How do I request a new laptop?”

Document title: “Requesting a New Laptop Through the IT Service Portal”

Opening line: “To request a new laptop, log into the Service Portal and follow these steps...”

AI-Ready Knowledge Document Checklist

One focused topic per article

Clear, simplelanguage—no jargon or acronyms without explanation

Logical structure with headings, bullets, and steps

Descriptive, easy-to-search title

Keywords included naturally

Includes context: why/when to use this solution

Last updated date and version number included

Reset Service Portal Password for Windows Users

This article explains how to reset your Service Portal password if you're using a Windows device.

When to Use This Process

Use this guide if you’re unable to log in and need to reset a forgotten or expired password.

Steps

1. Go to serviceportal.company.com

2. Click “Forgot Password?”

3. Enter your company email address

4. Check your inbox for the reset link

5. Follow the link to set a new password

6. Confirm and save changes

Additional Information

• Your password must include 8+ characters, 1 number, and 1 special character

• If you don’t receive the email, check your spam folder

• Contact the Service Desk if the reset fails after two tries

Updating Your Profile Information in the Service Portal

How to Unlock Your Account

Last Updated: June 2025

Author: Alex McDowell - IT Knowledge Manager

Applies to: Windows Users, Service Portal, Password Reset, Password Expiration

‍

Download PDF