How to Write a Help Article an AI Can Answer

The heading is your strongest retrieval signal after the title. A passage under "Billing settings" competes poorly against a question phrased "How do I update my credit card?" even when both cover the same ground. Wording that matches how users actually ask gets matched more reliably, so use the words your customers use and the words your product uses (Zendesk help).

Question-shaped headings do two jobs at once. They align the chunk's embedding with the query, and they tell the model what the passage is for. Vague labels such as "Introduction" or "More information" waste that signal, and clear headings that describe what the section contains help both readers and machines interpret the content (Yoast).

To find the real phrasing, mine your sources rather than your imagination. Support ticket subjects, live chat openers, search queries that returned no results, and the questions customers ask in onboarding calls all hand you the exact words. One useful trick with numbers: pull the last 200 ticket subjects, group them by intent, and pick the most common phrasing for each group as your heading. If two phrasings are common, use one as the heading and work the other into the first sentence of the answer, since chunks carry both.

The title of the article still matters because generative systems use the article title alongside the best matching chunks to build a reply (Zendesk help). Make the title the umbrella question and the headings the specific variants, so title and chunks reinforce each other instead of competing.

After the heading, answer immediately. The best pattern is a direct answer in sentence one, and the condition or scope in sentence two. Do not warm up with context, and do not imply an answer: state it (Zendesk help).

Consider this before and after:

Weak: "Depending on your setup, there are a few things to keep in mind when it comes to exporting. Administrators usually have access to this feature."

Better: "To export a report as CSV, go to Reports > Export and choose CSV. You need the Admin or Editor role, and the export option appears only on the Team and Business plans."

The better version names the path, the format, the roles and the plans inside two sentences. An assistant that retrieves just that chunk can answer fully, with no follow-up and no guess. The weaker version forces the model to either ask a clarifying question or invent the path.

Two rules make this work at scale. First, repeat the question or topic from the title in the opening sentence, because the chunk may arrive without its heading in some pipelines and needs to restate what it is about (Zendesk help). Second, put exact UI labels, menu paths and error strings in the answer text, not inside screenshots. Text chunks are what get indexed, and images and videos carry little of the contextual signal a model needs unless they are described in writing (Zendesk help). If a screenshot is genuinely helpful for humans, fine, but every instruction inside it must also exist as a sentence.

A quick self-check: cover everything after the second sentence. Can a reader act on what remains? If not, the answer is not yet complete.

A chunk that covers two subjects produces weaker similarity scores than two chunks that each cover one, which raises the chance of the assistant pulling the wrong passage (Meilisearch). That is the mechanical reason behind the one-idea-per-section rule: content should completely cover a topic and avoid covering multiple unrelated topics in the same place (Zendesk help).

The clearest way to enforce it is structural. Make each heading a single question with a single answer. If a heading needs "and" to describe it, it is probably two articles or at least two sections. "How do I reset my password?" and "Why did my password reset link expire?" are different questions with different answers, even though they share a topic, and merging them dilutes retrieval for both.

Where you have multiple solutions for one problem, present each as its own instruction rather than nesting sub-steps inside a broader step (Zendesk help). This matters because a nested step reads as context for the outer step, so a chunk boundary can land mid-branch and cut the instruction in half. A flat list of alternatives survives that split far better.

There is also a maintenance argument. Research on retrieval pipelines tested page-level, section-level and token-based chunking across many documents and found that no single approach won everywhere: optimal strategies varied even among similar document types, with factoid questions favoring smaller chunks and complex analytical questions benefiting from larger ones or page boundaries (NVIDIA). You cannot control how your platform slices your text, but you can make every possible slice coherent by keeping each section to one idea. That is the only chunking strategy an author directly controls.

Duplicates are the other half of this problem. Two articles that state the same policy differently leave retrieval with no way to know which is current, so it picks one, and it may pick the stale one (HelpDocs). When you consolidate, delete the old version rather than leaving it published for human completeness. Remove redundancies deliberately (Zendesk help).

A retrieved passage is often presented to the model and to the user with none of its surroundings. Three habits make writing survive that trip.

Kill vague pronouns. Replace "it" and "they" with the noun. "It resets at midnight" becomes "The usage counter resets at midnight in your account's time zone." Guidance on AI-ready content names vague pronouns as a specific problem for exactly this reason (Zendesk help).

Remove positional references. Phrases like "as mentioned above," "see the section below" and "in that case" assume a page that the chunk no longer has. State the condition again instead. "In that case, contact support" becomes "If the export fails after three attempts, contact support with your workspace ID."

Define terms on first use in each section. Spell out acronyms and explain the term in full the first time it appears (Zendesk help). If a chunk is the first thing a model sees, "the SAML assertion" may be its only exposure to the term, so define it there.

A comparison helps decide how much to repeat. The cost of repetition is a little human redundancy. The cost of omission is a wrong or hedged AI answer.

The cross-reference rule deserves emphasis because it is the one teams push back on. Linking out is natural for humans, but AI-ready guidance explicitly asks for self-contained topics that avoid linking out (Zendesk help). Keep links for deep context, but never make a link the only place a step or condition exists.

Most support answers have a condition: plan, role, region, platform, or account type. When the condition sits in a separate "Before you begin" section, the chunk that contains the steps may not contain the condition, and the assistant will read the steps out to someone who cannot use them. Put the condition in the same passage as the answer.

A worked example shows the difference in outcomes. Suppose a customer on the starter plan asks an assistant "How do I add a second admin?" and your knowledge base contains the following passage:

• Heading: Can I add a second admin to my workspace?
• Answer: A workspace owner can invite a second admin by going to Settings > Members, selecting the person, and choosing Change role > Admin. Only the workspace owner can change admin roles, and only the Business and Enterprise plans support more than one admin.

An assistant retrieving that chunk can answer completely: the path, who can do it, and the plan requirement. Now suppose the plan requirement lived in a separate paragraph three screens above. The assistant retrieves the steps, omits the requirement, and the customer hits an error, which turns into a ticket. The rewrite costs one sentence and prevents the ticket.

Semantic retrieval makes this more important, not less. Meaning-based search can match "how do I get my money back" to a refund policy article even when the words differ (Fin). That is good when the passage is complete and bad when the retrieved chunk is only half the policy. If your refund policy differs by region, every chunk that mentions refunds should name the region it applies to.

A simple audit catches most violations. Open each article and search for the words "depending," "if you have," "some plans" and "certain roles." Each hit is a candidate for a condition that needs to move into the answer itself, next to the step it governs.

Writing to these rules is testable, and you should test rather than assume. The most direct method is to paste a single section into a fresh chat with no other context and ask the question your heading poses. If the model answers completely and correctly from that section alone, the section passes. If it hedges or asks for the plan, the section fails the retrieval test that a live assistant will run.

Build a small evaluation set from real queries. Take questions customers actually asked, pair each with the article you expect to answer it, and check two things: that the right passage is retrieved at all, and that the retrieved passage contains the complete answer. Retrieval quality has measurable components, including precision (whether each retrieved chunk is relevant) and recall (of all chunks containing the answer, how many were found) (Meilisearch). You do not need a full metrics pipeline to benefit from the idea. You need to know whether the right chunk surfaced and whether it was sufficient on its own.

Keep the test set small and honest. Five to ten questions with a clear expected answer beat a hundred vague ones, and they double as a regression check when you edit an article. When you change a policy, rerun the set to confirm the new article now wins over the old one.

For teams running an assistant against a large knowledge base, the writing fixes and the retrieval fixes compound. If you are building the assistant side as well and want one API key across text, embedding and other models, Quanta Inference provides that through an OpenAI-compatible interface. But the order matters: fix the content first, because no model choice rescues a passage that never contained the answer (HelpDocs).