TOF-444: Split the troubleshooting FAQ mega-page into per-topic, per-question pages

[Copilot]

Splits troubleshooting/faqs.mdx — 70 questions on one URL — into seven per-topic pages, each question its own ## heading.

Relates to: https://linear.app/mixpanel/issue/TOF-444/aeo-qw7-split-the-troubleshooting-faq-mega-page-into-per-topic-pages

Why this matters for AEO

The old page had good answers. The problem was packaging: answer engines retrieve passages but cite URLs, so one URL cannot win 70 distinct queries no matter how well written it is.

Three measured effects, from the AEO plan:

Lever	Evidence
Title matching the query	Semantic similarity between page title and user query is 0.602 for cited pages vs 0.484 for non-cited — the largest single predictor measured. (Ahrefs, 1.4M-prompt ChatGPT study, Apr 2026)
Answer-first openers	38% of citations come from a page's first 100 words. Pages that answer early were cited 45% vs 23%. (Surfer, 100K-citation study, Jun 2026)
One question per URL	Engines retrieve passages but cite URLs; only 38% of AI Overview citations rank top-10 for the query. (Google GEO guidance, May 2026)

Concretely: a page titled "Frequently Asked Questions" matches almost nothing. Seven pages titled for their topic, each with 10ish question headings whose first paragraph is the answer, match the way people actually ask.

Why ## headings instead of accordions. Accordion titles generate no heading anchors, so a passage could be retrieved but not deep-linked, and nobody could share a link to one answer. Each question now has its own anchor. Visible Q&A copy is also what still helps — FAQ schema markup was deprecated in 2023 and correlates with slightly fewer citations, so the win here is structural HTML, not markup.

Descriptions were added to all seven pages. Mintlify generates llms.txt from that field, and an entry without one renders bare.

Changes

Seven new pages under troubleshooting/: general, sending-data, identity-management, building-reports, exporting-data, managing-projects, protecting-user-data.

Each opens with a one-line orienting sentence, then ## per question with the answer directly beneath.

/troubleshooting/faqs stays live as a hub. An earlier revision redirected it to /troubleshooting/general. That was wrong: Mintlify redirects cannot match a #fragment, so /troubleshooting/faqs#exporting-data-from-mixpanel would have landed on an unrelated page at a dead anchor. The URL is now an index page whose seven ## headings are copied verbatim from the original, so every existing deep link still resolves. It also links the Funnels and Group Analytics FAQs.

docs.json — FAQs tab becomes a group listing the hub plus all seven pages.

Bug fixes found during the split: two internal links in sending-data were missing a leading /.

Verification

• 70 questions before, 70 after. Titles byte-identical and in the same order.
• Zero answer lines lost — every non-trivial line of every original answer was matched in the new files.
• Code fences balanced; the two ```jsx blocks in identity-management survived dedenting intact.
• All seven original section anchors resolve against the new hub.
• Repo-wide grep: no remaining links to the old page.
• Checked against rec add workflow and code owners #3's merge requirement — the split produced zero overlapping questions with the existing Funnels or Group Analytics FAQ pages, so there was nothing to merge.

[linear-code]

TOF-444

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
mixpanel-docs	🟢 Ready	View Preview	Aug 18, 2026, 7:03 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
docs.json	Registers the FAQ hub and all seven topic pages in navigation.
troubleshooting/faqs.mdx	Retains the legacy URL as a hub linking all topic and feature-specific FAQ pages.
troubleshooting/general.mdx	Adds descriptive metadata and converts questions to search-friendly H2 sections.
troubleshooting/sending-data.mdx	Moves sending-data answers into a dedicated page with corrected absolute links.
troubleshooting/identity-management.mdx	Moves identity questions into a dedicated page using H2 headings.
troubleshooting/building-reports.mdx	Adds a dedicated reports FAQ page with descriptive metadata.
troubleshooting/exporting-data.mdx	Adds a dedicated data-export FAQ page with descriptive metadata.
troubleshooting/managing-projects.mdx	Adds a dedicated project-administration FAQ page with descriptive metadata.
troubleshooting/protecting-user-data.mdx	Adds a dedicated privacy FAQ page with descriptive metadata.

_{Reviews (5): Last reviewed commit: "Merge branch 'main' into copilot/tof-444..." | Re-trigger Greptile}