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 the exact order you set by dragging them 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 one database transaction, so another product's FAQ set is never mixed into it.

Put your most common questions at the top. 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, and the next conversation has it.

Keeping them in Markdown#

FAQs can live in your repository too. Put them in a faqs/ directory in a CLI docs project: the first heading in each file is the question, the rest is the answer, and filename order becomes FAQ order.

See Project layout.