Introduction
When you build an FAQ into your own site, the first decision is where the data lives and what shape it takes. How lightly you can build that part determines how much effort operations will cost later. Make it elaborate and every single fix needs a developer; start without deciding where things live and nobody can tell which file is current.
This article covers the data design we used when building an in-house FAQ for an apparel and gear EC site. Per-category JSON files (readable data files listing field names and values) act as the source data, production display is served from Vercel KV (a store built for fast reads and writes), and search runs off a separately generated index. Three layers. It's more than plain text files can handle for search, and less than a full database is worth building — this design aims at the middle.
FAQ Content Lives in Per-Category Files
One File per Category
The FAQ spans about ten categories and 100-plus questions. Put all of that in one large file and fixing a single answer means opening the whole thing, with changes hard to trace. So it's split into one file per category: "Shipping & Delivery," "Returns & Exchanges," "Account Registration," and so on. Adding a category means adding a file. Because each edit stays inside one file, several people can work at once without their changes colliding.
Four Fields Are Enough per Question
Each FAQ entry carries four pieces of information: an identifier, the question, the answer body, and the display order within its category. More fields would mean more expressive power, but also more input boxes in the admin screen and more work for whoever is editing. As long as the answer body allows simple links and emphasis, four fields cover almost everything. Keeping the structure flat also keeps admin editing and change-history review straightforward.
The table makes the point: one FAQ entry is built from this much information and no more.
Why We Started with Files Instead of a Database
Honestly, standing up a database for an FAQ felt like overkill. There are a few hundred entries and updates don't happen daily. Files can go straight into Git (a system that manages files while recording their change history), so who changed what and when is recorded automatically. There's also none of the structural migration work a database demands every time you add a field. Start small, revisit if the count grows — that order has held up fine.
Display Data Is Served from a Fast Store
Files Hold the Truth, Users See KV
Files are good for management, but reading and parsing them every time a user opens a page isn't efficient. So the files stay as the reference version of the data, while actual display is pulled from Vercel KV. Update a file, copy it into KV, and what users see is always the KV side. Easy management and fast display, without trading one for the other.
Keys Are Designed to Fetch One Category at a Time
Data sits in KV per category. When a user opens the "Returns & Exchanges" page, all they need are that category's FAQs — there's no reason to load all 100 questions. Using the category name as the lookup key means the whole set comes back in one fetch. Smaller fetches display faster, and adding categories doesn't change how fetching works.
Sister Sites Are Separated by Site Name
We were running several sister EC sites, so the store also distinguishes data by site. Making the lookup key "site name plus category name" lets the same mechanism serve any site's FAQ. Adding a site means preparing its files and copying them over. Since the data shape and the display mechanism are shared, nothing gets rebuilt per site.
Edit the source data that's kept with full change history
Reflect the update into Vercel KV
Regenerate the index that spans every category
Category pages and as-you-type search now show the latest content
Edit the source, copy it to two destinations — display and search — and only then does it reach the user's screen.
A Second Index for Searching Across Categories
Users Don't Know Which Category Their Question Is In
Categories help the people managing the FAQ, but not always the people searching it. Someone looking into "refunds" doesn't know whether that sits under "Returns & Exchanges" or "Payments," so they end up opening categories one by one. Past 100 questions, that gets tedious fast. So we generate a separate search index (the data equivalent of the index at the back of a book) covering every category, letting users search by words alone.
Light Preparation to Absorb Spelling Variations
The index includes both the question text and the answer body, since people often search for a word that only appears in an answer. Adding light normalization on top — unifying full-width and half-width characters, matching upper and lower case — visibly stabilizes how well searches hit. Without standing up a dedicated search engine, this much preparation is enough to make typed words find the right answer.
The Index Is Rebuilt Every Time the Data Changes
The index is a copy of the FAQ content, so if the source is updated and the index isn't, search results stop matching what the pages actually say. To avoid that, rebuilding the index is part of the update procedure. At a few hundred entries a full rebuild finishes instantly, so there's no clever partial-update logic to maintain. The rebuilt index also goes into KV, returning candidates as the user types.
You Don't Need a Heavy Search Engine
For an FAQ in the hundreds, a pre-generated index plus light normalization is plenty. Build small first and strengthen it only once the count grows and accuracy starts to fall short. That order costs less to build and less to operate.
Summary
The FAQ data design rests on three pieces: per-category files as the source data, Vercel KV for display, and a pre-generated index for cross-category search. More capable than plain text, lighter than a database. For an FAQ in the hundreds, that weight turned out to be about right.
An AI agent (AI-assisted development) helped lay out and compare the options behind these choices. With the decision points organized, this is well within reach even without an engineering background. For the full picture, see Building an In-House FAQ System.