---
title: Write docs for better answers
description: Structure docs so readers and the Knowledge Assistant can find the right answer.
---
Knowledge Assistant 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 the assistant 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:
```mdx
## Publish dashboard changes
## Add a custom domain
## Fix a missing internal link
```
Avoid headings that only make sense inside the page:
```mdx
## 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.
```mdx
Add the page to `docs.json` navigation, set it as the home page, or link to
it from the navbar or footer.
```
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 the assistant 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.
```mdx
---
title: Deployments
description: 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
Write clean MDX.
Improve endpoint answers.