Introduction
The point people disagree on most in FAQ operations is who gets to edit the FAQ. Support staff want to fix an outdated answer the moment they spot it. Developers want the data managed properly, with history. Both positions are reasonable, and letting only one win always costs you something. Admin-screen-only editing leaves no record of why things changed; file-only management means even a typo needs a developer.
This article covers how we set up two editing entry points for an apparel and gear EC site — staff through an admin screen, developers through files — and connected them with a sync mechanism. Edit from either side and the data still converges into one. The mechanism itself isn't complicated, but running two entry points means a handful of procedures you have to agree on in advance or things go wrong. Those agreements are included here.
Two Editing Entry Points
Staff Edit Through the Admin Screen
Most people who want to fix an FAQ never touch code or a file-management system. When someone handling inquiries notices "this answer doesn't match our current shipping rates," what matters is being able to fix it right then. So we built an admin screen you log into with a one-time password (a single-use code issued each time), where the question, answer body, and display order can be edited directly. Whoever needs to edit can do so, without specialist knowledge, at the moment they notice.
Developers Manage Files with Change History
Developers, meanwhile, handle the per-category files in Git (a system that manages files while recording their change history). Adding categories, bulk edits that reshape how answers are written, rolling the FAQ out to a sister site — that work deserves a working branch and a review before it goes live, the same as code. With Git, when, who, and what changed is all recorded, and a bad change can be rolled back.
Edit question text, answers, and ordering directly from the admin screen. They own everyday small fixes
Manage the files with full change history. They own category changes, bulk edits, and site rollout, with review
Same FAQ data, two entry points — one for everyday fixes, one for larger changes.
Decide Who Owns What in Advance
Once the entry points are split, put the boundaries into words. Wording fixes, answer updates, and reordering go to staff; category structure, multi-site rollout, and changes to the data format go to developers. Leave the line vague and either staff attempt a large change that gets messy, or small fixes end up waiting on developers. The genuinely ambiguous case is "a question that doesn't fit anywhere existing but doesn't warrant a new category," so the rule is to ask developers in that situation — which keeps things moving.
Connecting the Two Entry Points with Sync
One Process Pushes Out, One Pulls Back
With two entry points, "which side is current" comes up immediately. Bidirectional sync answers it. One process sends the file contents prepared by developers out to the production data (faq-push), and one brings the latest admin-screen edits back into the local files (faq-pull). Batched changes go out; staff fixes come back. It's this round trip that lets the two entry points coexist.
The Procedure That Keeps Staff Edits from Being Overwritten
The costly failure is developers pushing out stale files and wiping content staff had fixed in the admin screen. An answer silently reverts to its state from a few days ago, and nobody notices. To prevent it, the operational rule is that development work starts by pulling the latest content back first. "Pull before you touch it," consistently applied, all but eliminates this class of accident.
The Search Index Is Rebuilt After Every Release
The FAQ also has a separate index used for searching across categories. Update the content but leave the index stale and the wording shown in search results stops matching the pages themselves — a user finds an answer in search, opens it, and reads something different. So rebuilding the index is built into the end of the release process, keeping page content and search results identical.
Bring the latest admin-screen edits into the local files
Branch off, make the change, and have it checked
Reflect the change into the production store and publish it
Regenerate the cross-category index so search matches the pages
Pull, edit, push, rebuild. The value is in running those four steps in the same order every time.
Agreements That Prevent Accidents
Limit Who Can Log In
The admin screen handles public FAQ content, but you still don't want it editable by anyone. One-time password login limits who can edit. Compared with handing out a shared password, it handles staff turnover better and there's no password anyone has to write down somewhere. It suits a screen that non-technical staff use daily.
Sister Sites Run the Same Procedure
Because the same mechanism runs on the sister EC sites, both the editing entry points and the sync steps are shared across them. Staff only have to keep track of which site's FAQ they're editing; there's no separate procedure to relearn per site. Developers just switch which site the push and pull target. Keeping the operational procedure down to one version matters more as the number of sites grows.
Write the Sync Timing Down
A sync mechanism only works if you've decided when to run it. "Always pull before starting work," "after publishing, rebuild the index" — that timing lives in a short operational document. New people can run the same procedure, and anyone who forgets a step has somewhere to check. These agreements do as much for stability as the mechanism itself.
Watch Out for Overwrites
Pushing out stale files erases the latest changes staff made in the admin screen. Make "pull before you start work" a step nobody skips, so staff fixes never get lost.
Summary
FAQ editing works through two entry points — staff in the admin screen, developers in files — connected by push and pull sync. Neither the desire to fix things immediately nor the desire to manage data properly has to be sacrificed. An AI agent (AI-assisted development) built the sync processes themselves, but what actually keeps operations stable day to day is the "pull before you touch it" rule.
For details on how the data is held, see FAQ Data Management and Search Index with JSON + KV; for the full picture, see Building an In-House FAQ System.