Articles and sections

Your help center is the single most important thing in AskVoro. It's what visitors read, what the widget lists, what the public docs site publishes — and what the AI answers from. Everything else is plumbing around it.

Articles#

An article has a title, a Markdown body, a published flag, and a section.

Published is the boundary that matters. An unpublished article is invisible to visitors, invisible on the public docs site, and invisible to the AI. Drafts are genuinely private, so there's no risk in leaving a half-written article around.

Sections#

Sections group articles — "Getting started", "Billing", "Troubleshooting". Each has a title and a position, and positions order them in the widget and on the docs site.

An article doesn't need a section. Articles without one are Uncategorized, which is a real, durable state rather than an error — plenty of help centers never need more.

Ordering#

Drag articles within a section to reorder them. The order you set is the order visitors see.

Writing for an AI as well as a person#

The AI reads the same articles your visitors do, so the qualities that make an article good for a person mostly help it too. A few things matter more than usual:

One question per article. An article titled "Billing" that covers plans, invoices, refunds and VAT gives the AI four half-answers. Four articles give it four good ones.

Say the words your customers say. If they say "cancel my subscription" and you wrote "terminate your plan", write both.

Put the answer first. Lead with the answer, then the caveats. Both people and models weight the opening lines heavily.

Be explicit about the edges. "Refunds within 30 days" leaves day 31 to invention. "Refunds within 30 days of purchase. After 30 days we can't refund, but contact us and we'll look at it" leaves nothing to guess.

Don't rely on layout to carry meaning. A table that only makes sense alongside a screenshot reads as noise to a model. Say it in a sentence too.

Two places to write them#

Everything above works the same whether you write in the dashboard or keep Markdown in your repository and push it with the CLI.

Dashboard: fastest for a quick fix, and anyone on your team can use it.

CLI: docs live in git, get reviewed in pull requests, and ship with the code change that made them necessary. See the CLI section.

You can mix the two. Records created only in the dashboard are never claimed by the CLI. If someone edits a CLI-owned record in the dashboard, pull it back to the repository before editing; a later push intentionally makes the repository copy authoritative.