Skip to main content

​
Docs restructure — learnings + plan

Synthesis of how Bun, Next.js, and Resend (all effectively Mintlify-shaped) build their docs, and the plan to apply it here. This is the working spec for the restructure.

​
What the three best-in-class docs do (converged)

  1. Tabs = reader intent, stated to the reader. The tutorial / guide / reference triad:
    • Learn in order (Getting Started / tutorial), look up a how-to (Guides), look up a fact (Reference / Concepts / how-it-works). Next.js literally names them on the landing page.
  2. Drop numeric prefixes. Order lives in docs.json, never in the slug. Slugs are hyphenated, keyword-rich topic/question phrases; the URL reads as a breadcrumb. Troubleshooting/FAQ slugs are the literal question (Resend: /knowledge-base/how-do-i-avoid-gmails-spam-folder).
  3. Answer-first page anatomy. Front-matter title (H1) + a one-line description that is the answer (rendered as the subtitle + meta description; never repeated in the body). Then lead with value — an example, <Steps>, or a decision table — in the first screen. Self-contained, anchor-linkable H2s. “See X” / “Next steps” sign-off. No throat-clearing.
  4. Decision/summary table at the top of any “several ways to do X” page (Next.js redirects page).
  5. “Good to know” callouts for gotchas; dense cross-linking, no dead ends.
  6. Mintlify components used purposefully: <Steps> (procedures), <CardGroup>/<Card> (landing routers + next-steps), <Tabs>/<CodeGroup> (variants), <Accordion> (FAQ / hide long secondary steps), <Note>/<Warning>/<Tip> callouts, <Frame> (screenshots), <ParamField> (reference).
  7. GEO: description written as the answer; question-shaped titles/slugs; llms.txt index linked from the landing; each page also served as clean markdown. (We already generate llms.txt + .md.)

​
Our new information architecture

Map our content onto the triad. Tabs in docs.json:
TabDir (URL)What it is
HomeindexLanding / router — cards + CTAs, not prose.
Guidesplatform/The how-to library — task-first “How to…” pages. Landing = the How-to index (how-to), then task groups (Setup, Keywords, Landing pages, Blog, Publish, Analytics, Compliance, Diagnose). (Merges the old “How-to” + “Part 2 Platform” tabs.)
Conceptstheory/The Synscribe way of SEO/GEO — the “why / how it works.”
Playbookssops/SOPs for running accounts at scale (AM-facing).
Build docs(meta)Internal: plan, journal, conventions, gap register, mined sources.
Note on dir naming: the founder’s example was part-2-platform → platform. I read that as “strip the part-N- prefix” and named the three sections platform / theory / sops (clean, no numbers), with intent-named tabs (Guides / Concepts / Playbooks). Easy to rename the dirs to guides/concepts/… if preferred.

​
Slug scheme

  • Dirs: part-1-theory → theory, part-2-platform → platform, part-3-sops → sops.
  • Files: strip the numeric prefix. 2-0-2-working-across-clients → working-across-clients, 1-4-serp-cliff → serp-cliff, 3-1-onboarding-month-1 → onboarding-month-1, 2-7-1-set-up-evaluator → set-up-evaluator. index.md and how-to.md unchanged.
  • Order is preserved by docs.json (explicit page arrays), not filenames.

​
Page-anatomy template (applied to every page in the writing pass)

---
title: "How to <task>"          # the search query
description: "<one-line answer>"  # the answer, not a label; Mintlify renders it as the subtitle
part / audience / video / status / task / feature / persona / intent / keywords
---

<Answer paragraph: 1–3 sentences. The direct answer. Names the surface + Pi skill. Links onward.>
<Merge the old Answer box AND the old intro into THIS single lead — no duplication.>

## <first task-shaped H2>
...

**Next / Related:** …
  • No body # H1 (Mintlify renders the title). (Already stripped from all pages.)
  • No stacked intro — one answer-first lead, not “Answer box” + a second intro paragraph that repeats it.
  • Multi-option pages get a decision table up top. Gotchas go in > **Good to know:** callouts.

​
Execution phases

  1. Slugs + IA (mechanical, scripted, fully tested): rename dirs/files, rewrite all internal links, rebuild docs.json tabs, rebuild the how-to router. Verify: mint parse + internal links + anchors.
  2. Writing pass (per-cluster subagents): apply the page-anatomy template; reconcile the Answer-box/intro duplication; add decision tables/callouts where they help; keep facts/prompts/videos.
  3. Audit: browser-test every page (rendered, no dup title/body), independent judge, full link test (files + anchors) on the running site; fix everything found.