Docs audit: landing page & new-user flow restructure proposal

[bobbyg603]

Docs landing page & new-user flow: diagnosis and proposed restructure

From the 2026-07 docs audit. Three independent analyses (new-user first-crash journey, findability-by-job, information architecture) converged on the findings below. Everything is grounded in specific pages; file paths are relative to the docs repo root.

Diagnosis

The landing page is an orientation letter, not a router. The five jobs users actually arrive with — (1) integrate my platform, (2) my crash isn't showing up / missing symbols, (3) look up an API, (4) admin/billing task, (5) evaluate BugSplat — mostly have no first-class entry. "Integrations"/"SDKs" appears nowhere as a label (reaching the Unity guide takes 3–4 clicks through a section called Getting Started); "API" appears once, mid-sentence in prose; Troubleshooting (the purpose-built page for job 2, with Missing Crashes / Missing Symbols sections) is linked from nowhere on the landing page and missing from the 6-step checklist.

The new user is handed two competing quickstarts. The landing hero links the 5-minute guide while the equally-weighted Getting Started card leads to a "6-Step Checklist" that also claims to be "the quickest way to get started" — neither cross-references the other. Meanwhile the sidebar (SUMMARY.md) buries the 5-minute quickstart dead last under Getting Started, after the entire 40+ page Platform Integrations tree. And the 5-minute guide's step 4 tells readers to click an "In a hurry? Post a sample crash instead" button that only exists in the in-app onboarding viewer, not on the public docs site.

Structure debt compounds it. "Introduction" actually contains the whole product (API reference, symbols, integrations, support responses all live under it). The reference/ tree is an orphaned near-verbatim duplicate of the live API docs; administration/paid-plans-and-upgrades/ is an orphaned predecessor of billing/ with contradictory pricing; the changelog has three conflicting homes (SUMMARY → changelog.bugsplat.com, README → a login-only app.gitbook.com URL, plus an orphaned changelog/changelog.md frozen in 2021); Education's how-tos/FAQ largely re-index Development pages, giving symbol upload five homes; and integration pages nest 5 sidebar levels deep (e.g. Introduction → Getting Started → Platform Integrations → Desktop → C++ → Full Memory Dumps).

Proposed landing page (top to bottom)

1. "New to BugSplat?" strip — one labeled card: Post your first crash in 5 minutes (the single canonical quickstart; see below).
2. "Integrate your platform" card grid — the five integration categories (Desktop / Cross-Platform / Game Dev / Mobile / Web) surfaced directly, in user vocabulary.
3. "Fix a problem" — Troubleshooting + the missing-symbols FAQ, deep-linked ("My crash isn't showing up" → troubleshooting.md#missing-crashes).
4. "API Reference" — dedicated card to the web-services docs (Stripe/Sentry convention: API is always one click from the landing page).
5. "Using the app" / "Admin & billing" — current Development and Administration entries.
6. "What is BugSplat?" — un-hide about/what-is-bugsplat.md for evaluators, at the bottom.

Individually-actionable changes

Ordered so each stands alone; the first five are the highest-leverage.

1. Reorder SUMMARY.md: move the 5-minute quickstart from last to first under Getting Started.
2. Pick one canonical quickstart: keep the 5-minute guide as the "fast path" hero; reframe the 6-Step Checklist as the "thorough path" and cross-link both explicitly.
3. Fix the 5-minute guide's step 4: remove/replace the "In a hurry?" in-app-only button instruction (public readers hit a dead end).
4. Add Integrations + API Reference + Troubleshooting entries to the landing page (sections 2–4 above).
5. Delete the orphaned reference/ tree (4 pages duplicating live API/platform docs) — or convert to GitBook redirects.
6. Delete orphaned administration/paid-plans-and-upgrades/ (superseded by billing/; its pricing sheet contradicts current pricing).
7. Resolve the changelog: one public URL used identically in SUMMARY.md and README.md; delete the orphaned changelog/changelog.md.
8. Collapse Education re-indexes: one home per task (prefer the Development/Production page); make FAQ/how-to twins redirects. Symbol upload should have one canonical page instead of five.
9. Delete filename-twin orphans from botched renames (missing-bugsplat.dll.md, what-is-bssndrpt.exe.md, best-practices-for-adding-users…).
10. Flatten integrations nesting by one tier (drop the per-language wrapper level) so no page is more than 3 clicks from a section root.
11. Standardize the onboarding feature's name (currently: "onboarding tool", "Onboarding process", "onboarding helper tool", "guided onboarding", "new user walkthrough tool" across five pages).
12. Add a "create a database first" prerequisite note to the integration category README and SDK leaf pages.
13. Move about/misc/giveaways/ (12+ dated pages) out of the docs; rename administration/introduction/ → administration/user-management/.
14. Longer-term: rename/split "Introduction" so API, Symbols, and Integrations are findable as top-level sections ("Guides" / "API Reference" / "Integrations").