Should the FAQ repeat what the policy pages say?

Yes, in short form, in the customer's words. The policy is the authority and the FAQ is what matches the question. Where they could drift, keep the number or the rule in one place and let the FAQ answer describe it rather than restate it precisely.

Is it better to upload the FAQ as a file than to crawl the page?

It is more predictable, because you control the structure exactly and there is no interactive layer between you and the text. Plain text and Markdown files are both accepted. Just index one or the other, since a page and an upload that have drifted apart are two different documents.

How many questions should one page hold?

Few enough that they are all about the same subject. There is no magic number, and the failure mode is not length as such but sameness: once every passage on a page looks like every other, the retrieval has nothing to choose on and the answers get vaguer.

Source material

The best material you own, arranged in the way that helps least

An FAQ page is already question and answer pairs, already in customer language, already covering the things people ask. It should be the single strongest document any business has. It usually is not, and the reasons are all structural: everything is on one page, the questions are phrased the way the business would ask them, and the answers depend on each other.

Why this one is harder than it looks

Accordions are the first problem and they are subtler than they look. The answers are usually present in the page rather than fetched on demand, so they are read. What is at risk is the pairing. Extraction prefers semantic structure and falls back to the whole container's text when a page yields too little, and the fallback loses the heading structure, which welds forty questions and forty answers into one undifferentiated block. What comes out of that is a passage containing three questions and two answers that do not belong to them.

The second problem is size. One page carrying every question a business has ever been asked produces a great many passages that all look alike: same register, same vocabulary, same subject matter. Six passages are retrieved for a question, and on a page like that, all six are plausible and only one is right. The strongest material in the business ends up competing with itself.

Third, the questions are phrased the way an internal team would phrase them. What is your delivery policy. What are our service level commitments. Nobody types those. They type when will it come and is it here yet. A question heading is the strongest matching text on the whole page, so a heading in the wrong voice throws away the biggest advantage this document format has.

Fourth, and this one is specific to FAQ pages, answers reference each other by position. As mentioned above, see the previous question, this also applies to the section below. Position is exactly what a passage does not have. Every one of those phrases is a pointer into a document that is no longer there.

What it has to contain

Structure rather than wording. A passage pulled out of this document has to stand on its own, because that is the only form in which it will ever be read.

Structural requirements
One question per heading, in the words a customer types	Lowercase, direct, ordinary. How long does delivery take rather than delivery timescales. If people ask the same thing two ways, use one as the heading and put the other phrasing into the first line of the answer, so both are in the same passage.
An answer that stands alone under each heading	Complete without the question above it and without any other answer on the page. That usually means restating a little of the question inside the answer, which reads slightly redundantly and is the property that makes a passage safe.
Topic pages rather than one long page	Delivery, returns, payment, accounts, the product itself. Each its own document with its own questions. Fewer competing lookalike passages per question, and a page somebody might actually read to the end.
No references by position anywhere	Nothing that says above, below, previously, or as covered elsewhere. Where two answers genuinely share material, write it into both rather than pointing from one to the other.
Text that is present without interaction	Whatever the page looks like, the questions and the answers have to be in the delivered text of the page, and structured so that each answer is attached to its own heading rather than pooled into one container.

The rewrite, in order

Rephrase every question into the customer's words

Take each heading and rewrite it as the message somebody would send. If your support inbox is available, take the phrasings straight out of it, because real phrasings beat imagined ones every time and this is the rare piece of writing where the source material is sitting in a folder.

Where a question is genuinely asked several ways, put the alternates in the opening line of the answer rather than creating near-duplicate headings. Duplicate headings create the competing passage problem you are trying to remove; alternate phrasings inside one answer simply widen what it matches.

Make every answer able to stand up alone

Read each answer with the question covered. If it starts with a word like yes, or it, or that, it is depending on the heading, and it will be quoted without it. Rewrite the first sentence so it restates enough of the subject to be self-sufficient.

Then hunt the positional references. Replace as mentioned above with the thing that was mentioned above. Replace see the returns section with the two sentences from the returns section that actually matter here. Duplication is the correct answer again, for the same reason it was in the policy documents: a passage cannot follow a pointer.

Break the page up by topic

Split the one long page into several shorter ones by subject. This helps a person, who now has a page they can finish, and it helps retrieval, because the passages competing for a delivery question are now the ten from the delivery page rather than the eighty from everything.

Keep each page focused enough that its questions are genuinely about one thing. A page called Other, or General, will refill with the same undifferentiated material the original page had, and it will do it within a year.

Check the page shows its text without any interaction

View the delivered source of the page, or turn scripting off, and look for your questions and answers. If they are present, you are fine, and the remaining risk is the pairing, which is why each question should be a real heading with its answer directly under it rather than a styled row in a list.

If the answers are not in the delivered text, because they are fetched only when somebody opens a panel, the page cannot be indexed by a crawl at all. In that case publish the same content as a plain document and upload it, which takes an hour and is a better use of the time than fighting the page.

What happens if you skip it

Six passages retrieved and every one of them nearly the same

The question is specific and the page has the answer. What comes back is assembled from six passages off the same long FAQ page, all of them adjacent, all in the same voice, one of them containing the actual answer and the others containing questions and part-answers about neighbouring subjects. The reply hedges, covers two things that were not asked, and buries the sentence that mattered.

It is not a wrong answer, which is why it survives so long unnoticed. The cost is that the best material the business owns produces mediocre replies, and whoever set it up concludes the assistant is vague, when what is vague is a page carrying eighty near-identical passages and asking a retrieval system to pick between them.

Check it against this

Before you index it

Every question heading is phrased the way a customer would type it
Every answer is complete with the question hidden
No answer refers to another by position
The page has been split into topics, none of them called general
Questions are real headings with their answers directly beneath
The questions and answers are in the delivered text of the page
Alternate phrasings live inside answers rather than as duplicate headings

Questions

Should the FAQ repeat what the policy pages say?: Yes, in short form, in the customer's words. The policy is the authority and the FAQ is what matches the question. Where they could drift, keep the number or the rule in one place and let the FAQ answer describe it rather than restate it precisely.
Is it better to upload the FAQ as a file than to crawl the page?: It is more predictable, because you control the structure exactly and there is no interactive layer between you and the text. Plain text and Markdown files are both accepted. Just index one or the other, since a page and an upload that have drifted apart are two different documents.
How many questions should one page hold?: Few enough that they are all about the same subject. There is no magic number, and the failure mode is not length as such but sameness: once every passage on a page looks like every other, the retrieval has nothing to choose on and the answers get vaguer.

Keep reading

Try it on your own material

Upload a document or point it at your site, paste one line of HTML, then ask it something only your business could answer.

Start free See what it does