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 is one Markdown file in your docs folder: a title (its first # Heading), a body, 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. Articles publish when they sync; to keep a half-written one out of sight, leave it on a branch until it's ready.

Sections#

Sections group articles — "Getting started", "Billing", "Troubleshooting". A section is a directory with a section.json holding its title and 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#

Articles sort by filename, so prefix them 01-, 02- to set the order. The prefix never reaches the title or the URL. The order of the files 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.

Where you write them#

In your own GitHub repository, as Markdown. Every push to main publishes the folder, so docs get reviewed in pull requests and ship with the code change that made them necessary. The dashboard lists what synced but has no editor. See Publish your docs from GitHub.