Writing AI-ready documentation

Joely's AI assistant answers customer tickets from your knowledge base. When you import a documentation page, Joely cleans it, splits it into short sections, and indexes each one so the AI can retrieve the passages most relevant to a customer's question and quote them in its reply.

That means the quality of the AI's answers depends directly on how your documentation is written. The AI can only be as accurate as the page it read. This guide covers how to write docs that retrieve cleanly and answer well.

The good news: none of this is AI-only busywork. Documentation that is clear, focused, and self-contained is easier for your customers to read on their own and easier for Joely's AI to retrieve and answer from. It is a genuine win-win — every improvement pays off twice: fewer tickets because people find the answer themselves, and better AI replies on the tickets you still get.

How the AI reads your docs

Before the rules, it helps to know what happens to a page after you import it:

Cleaning — navigation, sidebars, footers, cookie banners, and other boilerplate are stripped. Only the main content survives.
Sectioning — the cleaned text is split into short passages, mostly along your headings and paragraph structure.
Indexing — each section is stored verbatim (word for word) and indexed by meaning, so it can be found later.
Retrieval — when a customer writes in, Joely searches for the sections whose meaning is closest to the question, not just the ones sharing the same words. The best-matching sections are handed to the AI, grouped with their page title and link.
Answering — the AI writes a reply grounded in those sections. If your staff also taught it curated facts on the same topic, the curated facts win over documentation on conflict.

Two consequences drive every rule below:

The AI retrieves one section at a time, out of its original context. A section that only makes sense after the one before it will be retrieved alone and lose its meaning.
Retrieval is by meaning, but the text is stored verbatim, so exact error messages, commands, and config keys are preserved and worth including literally.

Structure each page into self-contained sections

The single most important habit: every section must stand on its own.

Use clear, descriptive headings. Sections are split along your heading structure. A page with good H2/H3 headings produces clean, well-scoped sections. A wall of text with no headings produces one blurry section that matches everything and answers nothing precisely.
One topic per section. Keep each heading focused on a single question or task. If a section covers three unrelated things, it retrieves for all three and dilutes each answer.
Repeat the subject; avoid back-references. Write "To reset the license key, open your dashboard…" — not "To reset it, open your dashboard…". Words like it, this, the above, and as mentioned earlier break when the section is read alone. Name the product or feature explicitly in the heading and the first sentence.
Don't hide the answer behind a link. The retriever pulls a single section, not the pages it links to. "See our installation guide" is useless when that section is read on its own. Put the actual answer in the section; use links only as an optional complement, never as the answer itself.
Front-load the answer. State the fact or the fix first, then explain. "The plugin requires MySQL 8.0 or newer." then the reasoning. Customers and the retriever both reward the direct sentence.

Format for clean retrieval

How you format a section changes how well it chunks and how reliably the AI reads it back.

Use lists deliberately. Bullet points for facts or options; numbered lists for steps that must happen in order. A clear list survives sectioning far better than the same items buried in a paragraph.
One instruction per step, no deep nesting. When a problem has several possible fixes, write each as its own step or section rather than as sub-steps inside a bigger one. Nested "if this, then maybe that, unless…" branches are hard to retrieve and easy to misread.
List every step. Write out the whole procedure, including the obvious first and last steps. The AI will not silently fill in a step you left implicit.
Prefer sentences to tables. A model reads prose more reliably than a grid. Keep tables small and simple, and restate any critical cell in a sentence nearby — a compatibility table is fine, but also write "Version 3 requires Windows 11" in plain text.

Write for the way customers actually ask

The retriever matches meaning, but you can make its job easy.

Use your customers' words, not only internal jargon. If people call it "the map file" and you call it "the geometry asset", include both terms at least once so the question and the doc line up.
Include exact error messages and commands verbatim. Customers paste the literal error into a ticket. Because sections are stored word for word, a page that contains the exact string Error 0x80070005: access denied is a strong match for a ticket quoting it. The same goes for command names, file paths, and config keys.
Spell out acronyms once. Write "server-side rendering (SSR)" the first time so both forms are indexed.
Phrase FAQ entries as real questions. "Why is my download link expired?" followed by a direct answer retrieves extremely well, because it mirrors how the customer phrases the ticket.

Give one canonical answer

Contradictions are worse than gaps.

One source of truth per question. If two pages answer the same question differently, the retriever may surface either one, and the AI cannot tell which is correct. Keep a single canonical page and link to it from the others.
Delete or fix deprecated pages. An outdated page indexed alongside the current one makes the AI confidently wrong. When you retire a feature, remove or update its page, then re-sync.
Avoid near-duplicate pages. Slightly different copies of the same content compete with each other in retrieval and add no value.

Organize pages so scoping stays accurate

Joely can scope a documentation page to a specific Tebex package, so a page about script A is never used to answer a ticket about script B. On import, it auto-detects the package from the page's H1, then its title, then its URL.

One product (or script) per page whenever you can. Mixed pages are harder to scope and cause answers to bleed across products.
Put the product name in the H1 and the page title. This is what auto-detection reads first, so it makes scoping reliable. A page titled "Installation" scopes worse than "MyScript — Installation".
Keep truly shared information global. Billing, licensing, and general setup that apply to everything belong on general pages (global scope), so they surface on every ticket regardless of package.

Keep the important content on the page

The cleaner keeps your main content and drops the chrome, but it can only index text that is actually there.

Don't hide answers behind clicks. Content that only appears after the reader expands an accordion or switches a tab may not be captured. Put essential information in the page by default, or give it its own heading or page.
Text, not just images or video. Joely indexes text. A screenshot of a settings panel, a diagram, or a tutorial video is not read when indexing your docs. If a step matters, write it out in text next to the visual.
No key facts in downloadable files only. A PDF or ZIP linked from the page is not indexed. Summarize its critical points on the page itself.
Trim noise with CSS selectors. If a page carries promo blocks, related-article rails, or comment threads that the auto-cleaner leaves in, use the import's CSS selectors (up to 10 to keep, 10 to remove) to target the real content. If a page comes back flagged "No content", it was almost all boilerplate — add real text or point the selectors at the main article.
Mind the size cap. Each page is indexed up to 100,000 characters. Very long pages are better split into focused sub-pages, which also improves sectioning.

Pick one language per page

Retrieval is cross-language: if a customer writes in a language different from your docs, Joely reformulates their question into your documentation's language before searching. So you do not need to translate everything.

Write each page in one consistent language. A single, well-written language is fully supported.
Avoid mixing languages inside a page or a section. It muddies the meaning the retriever indexes and weakens matches.

Keep it fresh

The AI is only as current as your last import.

Re-sync after you edit. Re-running an import or a source re-sync is cheap: unchanged pages are detected by a content fingerprint and skipped for free, and only changed pages are re-indexed. See knowledge sources and re-sync.
Remove pages you retire. Pages that disappear from your sitemap are flagged as possibly removed but never deleted automatically — delete them yourself so the AI stops quoting them.

Test before customers do

You don't have to wait for a real ticket to find the gaps.

Use Test knowledge. Open the Test knowledge playground, pick the same package scope a customer would hit, and ask the exact questions you expect. It uses the identical retrieval, prompt, and model as a live auto-reply, and shows the facts used so you can see which sections the AI pulled. Where the answer is wrong or vague, fix the underlying page and test again.
Fill the last gaps with Teach AI. Some answers live in your team's head, not in any doc. Capture those with Teach AI or manual facts. Because curated facts outrank documentation on conflict, they are also the right tool to correct a single stubborn answer without rewriting a whole page.

Checklist

Before importing a page, confirm:

Clear headings, one topic per section
Each section makes sense read on its own (no it / the above)
The answer comes first, then the explanation
Exact error messages, commands, and config keys are written verbatim
Customer-facing terms and synonyms appear at least once
No page contradicts another; deprecated pages removed
Product name in the H1/title for correct package scoping
Essential content is text on the page, not only in images, video, tabs, or downloads
One language per page
Tested with Test knowledge at the right package scope