Introduction
The thing that causes the most friction in FAQ operations is "who fixes the FAQ."
Staff want to "fix it the moment they notice," developers want to "manage the data properly." Leave those two unaddressed and they collide, don't they?
In this article, I explain how, for an apparel and gear EC site, I balanced two paths — staff edit in the admin UI, developers manage in Git — using push/pull scripts. Whichever path you touch it from, the data ultimately converges into one.
Providing Two Editing Paths
Floor Staff Edit from the Admin UI
Most of the people who want to fix an FAQ don't touch code or Git. When a customer support rep notices "this answer is out of date," it matters that they can fix it on the spot. So I built an admin UI you log into with OTP (one-time password) authentication, where question, answer, and display order can be edited directly. Anyone who needs to, can fix things when they need to, with no specialized knowledge. That's the staff-side entry point.
Developers Manage the JSON in Git
Meanwhile, developers manage the per-category JSON in Git. Large structural changes, adding categories, rolling out to multiple sites — that work should go through branches and review, just like code. Handling it in Git leaves a history of when, who, and what changed, and lets you revert when something goes wrong. Everyday small fixes go to staff, batched changes go to developers — a natural division of roles emerges.
Edit question, answer, and order directly from the OTP-authenticated admin UI. Handle everyday small fixes
Manage the JSON in Git. Handle structural changes, category additions, and site rollout with review
Bidirectional Sync with push/pull
The Roles of faq-push and faq-pull
With two paths, the question "which one is the latest" inevitably arises. Bidirectional sync scripts solve it. faq-push reflects the Git JSON to Vercel KV (production data), and faq-pull pulls the latest KV data — changed via the admin UI — back into Git. Batched developer changes go out via push; staff fixes are collected back via pull. It's this round trip that lets the two paths coexist without falling apart.
Not Losing Staff Changes
The scariest scenario is developers overwriting content staff edited in the admin UI by pushing stale JSON from Git. To prevent this, I made it an operational rule to run faq-pull first, before starting work on the development side. Enforce "pull before you touch it" and the accidents that wipe out staff fixes drop sharply.
Bring the admin-side latest changes into Git with faq-pull
Branch off, change the JSON, and pass review
Reflect to KV with faq-push and roll out to production
Regenerate the cross-search index to keep things consistent
Running Operations Safely
Separating Authentication and Permissions
Even though the admin UI handles public FAQ information, you don't want just anyone rewriting it. I limit logins with OTP authentication and restrict who can edit. OTP — which avoids password reuse and hardcoding — pairs well with an admin UI used by floor staff.
Deciding Sync Timing in Advance
push/pull are powerful, but leaving when to run them vague invites accidents. Writing timing into operational rules — "always pull before work," "after push, also update the search index" — lets you run the same procedure even as the person in charge changes. Beyond the mechanism, it's this decision-making part that quietly pays off, doesn't it?
Watch for Overwrite Accidents
Pushing stale JSON straight from Git risks erasing the latest changes staff made in the admin UI. Make "run faq-pull before you start work" an ironclad rule so you don't lose staff fixes.
Conclusion
FAQ editing is balanced through two paths — staff in the admin UI, developers in Git — synced bidirectionally with faq-push / faq-pull. The beauty of this setup is that neither "staff who want to fix things fast" nor "developers who want proper management" gets their needs crushed.
How to connect this FAQ to user self-service is covered in Connecting FAQ to the Contact Flow to Reduce CS Load. For the data-structure details, see FAQ Data Management and Search Index with JSON + KV.