FAQs

An FAQ is a question and an answer owned by one knowledge base. The same question can exist in another knowledge base, but cannot be duplicated inside one (case and surrounding whitespace do not make it unique).

Use one when the answer is short enough that making someone open an article would be silly. "Do you ship to Canada?" is an FAQ. "How international shipping works" is an article.

Ordering#

FAQs are shown in filename order — 01-, 02- — in ordered visitor surfaces such as the widget. The AI searches FAQ content by relevance; display position does not force search ranking.

The order is scoped to the knowledge base and saved in the same transaction as the rest of the sync, so another product's FAQ set is never mixed into it.

Number your most common questions first. It's the cheapest improvement available to you: most visitors read the first three and stop.

Writing them#

Ask the question the way a customer would. "Where's my order?" not "Order status enquiries".

Answer in the first sentence. An FAQ that opens with background hasn't answered anything.

Keep it to a few sentences. If the answer needs headings, it's an article. Write the article and let the FAQ point at it.

FAQs and the AI#

The AI reads your FAQs alongside your articles, so a good FAQ set directly improves its answers. It's also the fastest fix available when the AI gets something wrong: add the question with the right answer, push, and the next conversation has it.

Writing them in Markdown#

FAQs live in your repository with your articles, in a faqs/ directory at the root of the docs folder: one file per FAQ, the first heading is the question, the rest is the answer.

See Project layout.