Write Docs That Work Well With AI Answers

AI Answers works best when your Docs are clear, consistent, and easy to follow. If AI Answers misses details or uses the wrong context, you can update your articles and refine results over time.

This guide shares some practical writing tips that can help AI Answers use your Docs more accurately.

Write Clear Text Instructions

Images and videos are helpful visual guides for people reading your Docs, but they should support your instructions, not replace them. While this is true even when writing just for your customers, it's extra important for AI Answers. If your steps are only shown in a screenshot or video without written context, AI Answers will miss important details.

Note: Include text that explains what a customer should do and what they should look for. Don’t rely on images or video to communicate key steps on their own.

What to aim for:

  • Add a short sentence before (or after) an image that explains what’s happening.
  • If an image shows a UI detail that matters (a setting name, a button label, an option), include that detail in the text too.

Use Plain Language for First-Time Readers

Write your Docs for someone who is learning about your organization, product, or services for the first time. This helps customers move faster, and it gives AI Answers clearer source material to work from

  • Use short sentences.
  • Prefer common words over technical language that a new customer might not know or provide an explanation the first time you use technical language in an article.
  • Define any terms that a new reader might not know.

If you want a general set of writing principles to use as a checklist, Write the Docs (a wonderful community full of resources for documentation needs) has some great guidance here: Principles of Great Content.

Prefer Active Voice

Active voice helps customers understand what to do, and it can make your instructions easier for AI Answers to interpret.

Active voice examples:

  • “Select Save.”
  • “Turn on Notifications.”
  • “Choose Email as the delivery method.”

What to avoid:

  • “Notifications should be turned on.”
  • “The form can be submitted.”

Helpful resources:

Use Step-by-Step Instructions for Tasks

When a customer needs to complete an action, step-by-step instructions are usually the clearest format. They also reduce the chance that AI Answers will rewrite your process in a way that changes the meaning.

Recommended:

  1. Click Button name.
  2. Select Setting name.
  3. Click Save.
  4. Refresh the page.

Less clear:

  • “Click the button, then click save, then refresh the page.”

Tip: If an action has a specific order, make that order explicit. This helps customers follow along and helps AI Answers reuse the same sequence.

Review Results and Improve Over Time

It can take some experimentation to get the best results. Some best practices to help AI Answers and Docs stay up to date:

  • Review AI Answers conversations to see where responses fall short. See Manage AI Answers: Review Conversations for help on how to review these.
  • Decide if what's needed is an Improvement, a Guardrail, or an update to Docs.
  • Update the relevant Docs article to add missing context, clarify terms, or convert a paragraph into steps.

Over time, small updates will make AI Answers more consistent and reduce repeat questions.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.