Write docs for better answers

Ask AI is strongest when your docs are explicit, well structured, and written in the same language readers use when they ask questions.

The goal is not to write separate content for AI. The goal is to write better docs: clear headings, complete steps, visible constraints, and examples that answer real reader questions.

What Ask AI can retrieve

Radiant indexes readable page content, including headings, paragraphs, lists, tables, links, code blocks, step titles, accordion questions, tab labels, and OpenAPI metadata.

Use those structures intentionally. They help readers scan pages and give the assistant better retrieval handles.

Write searchable headings

Prefer headings that match the way users ask questions.

Use:

## Publish dashboard changes## Add a custom domain## Fix a missing internal link

Avoid headings that only make sense inside the page:

## Next## More details## Important

Include constraints near the steps

When a task depends on a plan, role, source type, or status, write that constraint near the procedure.

Good pages answer:

• Who can perform this action?
• Which plan includes it?
• What needs to exist first?
• What status should the user expect?
• What happens after they finish?

Use accordions for common questions

Accordions are useful for natural-language questions because the question title is meaningful on its own.

<AccordionGroup>  <Accordion title="Why is my page not visible?">    Add the page to `docs.json` navigation, set it as the home page, or link to    it from the navbar or footer.  </Accordion></AccordionGroup>

Do not hide required procedure steps inside accordions. Use them for FAQs, edge cases, and optional detail.

Keep important information in text

Screenshots and videos help readers recognize the interface, but the assistant needs text it can retrieve. If an image shows an important status, button, or error, also write the status, button name, or expected behavior in the page body.

Make API descriptions useful

For API reference pages, the OpenAPI source matters. Write summaries, descriptions, parameters, request bodies, responses, errors, and examples as if a reader might ask the assistant about them later.

Strong OpenAPI descriptions help Ask AI answer exact endpoint questions such as which method to use, which parameters are required, and what response shape to expect.

Add page descriptions

Use frontmatter description on important pages. Descriptions summarize the page for humans and generated surfaces.

---title: Deploymentsdescription: Understand deployment triggers, status, and rollout behavior.---

Checklist

Before publishing, check that the page includes:

• A clear title and description.
• Headings that match real user questions.
• Prerequisites, plan requirements, and permissions.
• Steps with expected outcomes.
• Status labels and what they mean.
• Links to related workflows.
• Text explanations for important screenshots.

Related pages