Help center

A help center is docs for end-users — people using your product, not building with your API. Support articles, FAQs, troubleshooting guides, billing questions. Different audience, different voice, different IA than developer docs.

Most help centers fail for one of two reasons: they duplicate support tickets (same question asked 30 times → not answered in docs) or they over-engineer the IA (10-level category trees nobody navigates). This guide covers the help-center patterns that work.

Help center vs developer docs

Mixing the two in one site confuses both audiences. Either separate tabs (NookDocs supports this) or separate subdomains (docs.acme.com vs help.acme.com).

The four section pattern

Most help centers fit this shape:

Advanced help centers add:

• Use cases / recipes — "How teams use Acme for customer research".

• Integrations — non-developer-facing ("How to connect Acme to Slack").

• Admin guides — for org/team admins vs individual users.

Voice tuned for non-technical users

Most technical-writing best practices still apply (style and tone), with shifts:

• More conversational. First sentence often asks the reader's question back: "Wondering why you got charged twice? Here's what happened."

• More reassuring. "Don't worry" appears here where it'd be banned in dev docs. End-users frame problems emotionally.

• More step-by-step hand-holding. Where dev docs assume readers know terms, help docs define every term on first use.

• Fewer links. Dev docs can link densely because engineers parse links fast. End-users get overwhelmed. 3-5 links per page max.

• More visual. Screenshots of every non-trivial UI step, not just tricky ones.

Before / after

❌ Dev-doc voice in help center
Rotate your API key by POST-ing to /v1/api-keys with a valid
authenticated session. The response returns the new key; the old key
is revoked immediately.

✅ Help-center voice
Your API key is like a password for your Acme integrations. If it
might have been exposed (you shared it by accident, or you're
rotating it for security), here's how to generate a new one:

1. Open **Settings** → **API keys** in the dashboard.
2. Click **Rotate key** next to the key you want to replace.
3. Confirm. Your old key stops working immediately — be sure to
   update any integrations using it.
4. Copy the new key and store it somewhere safe (password manager is
   ideal).

If an integration breaks after rotating, it's likely still using
the old key. Check the integration's settings.

Same information, different register.

FAQ pages that actually help

FAQ pages are the most-read + most-often-bad help content. Patterns:

Good FAQ pattern

<AccordionGroup>
  <Accordion title="Why was I charged twice this month?">
    Almost always, this is a proration — you upgraded mid-cycle and
    got charged the remaining days at the new rate. The higher charge
    is your new monthly amount, starting on the upgrade date. Check
    **Billing → Invoices** — both line items will appear there.

    If you see two full-month charges, that IS a billing bug. Open a
    ticket from Billing → Help; include both invoice numbers.
  </Accordion>

  <Accordion title="Why can't I delete my account?">
    Account deletion requires no active subscription, zero pending
    invoices, and the account to be at least 7 days old (anti-fraud
    delay). Cancel any active subscriptions first, wait for invoices
    to settle, then retry. Full walkthrough in
    [Cancelling your account](/account/cancel).
  </Accordion>
</AccordionGroup>

Each answer: the actual answer in the first sentence, the edge cases + escalation path after.

Bad FAQ pattern

❌ Too brief
Q: Why was I charged twice?
A: It could be a proration. Check your invoices.

❌ Too verbose
Q: Why was I charged twice?
A: Ah, this is a really common question. Our billing system uses
a technique called "proration" which is industry-standard. When you
make changes to your subscription mid-cycle, we calculate... (700
more words explaining billing theory)

❌ No escalation path
Q: Why was I charged twice?
A: It's probably a proration. [End of answer.]

Users stuck on "why was I charged" need: the answer, a self-serve verification step, and (for the 5% where the answer doesn't fit) a clear escalation path.

Troubleshooting trees

For issues with multiple possible causes, structure as a decision tree:

## My webhook isn't firing

### Is the webhook endpoint returning 2xx?

Check your server logs for any requests to the webhook URL in the
past 10 minutes.

**If yes — requests arrived but you expected different content:**
- Verify the `Content-Type: application/json` header was set.
- Compare the payload against [webhook schema](/webhooks/schema).

**If no — no requests arrived:**
- Is the webhook URL reachable from the internet? Test with
  `curl -X POST https://your.com/webhook -d '{}'`.
- Is the endpoint in the dashboard **enabled**? Check
  **Settings → Webhooks**.
- Has the endpoint failed more than 10 times? We auto-pause after
  repeated failures. Re-enable from **Settings → Webhooks**.

### If none of the above...

[Open a ticket](/support) with:
- Webhook endpoint URL
- The event ID you expected to trigger (from the event log)
- Your server's log showing no matching incoming request

Each decision point routes to a specific next-step. Users who can self-serve do. Users who can't arrive at the ticket form with the exact info support needs.

Screenshots in help content

Much more generous than dev docs:

• Every UI reference has a screenshot. "Click the Save button" → screenshot showing the button highlighted.

• Annotated with arrows or circles — end-users miss unmarked details.

• Retake every quarter — UI changes, screenshots age. See maintenance guide.

• Alt text is even more important — some end-users rely on screen readers; some on slow connections. See accessibility.

Exceptions where you DON'T need a screenshot: decisions with three+ variables (use a table) or long linear flows (use a video or GIF).

Support ticket integration

Help center + support team should share a priority queue:

Over ~6 months, a disciplined support-to-docs pipeline can reduce ticket volume by 30-50% on high-frequency topics.

When to use ticket-deflection chat vs docs

Many help centers add chatbots ("ask Oscar, our AI support agent"). The economics:

• Chat works well for — narrow-scope products with clear answers. "When does my trial end?" → chatbot can answer. "How do I integrate Acme with our custom auth flow?" → escalate.

• Chat works badly for — anything requiring judgement, anything where the LLM doesn't have access to user state, anything emotionally charged (billing disputes, account deletion).

• Docs always supplement chat — even the best chatbot routes to docs for long explanations. Your docs are the underlying source of truth.

NookDocs's AI assistant is a chatbot pattern, but powered by your docs as RAG source. Enable it on the help center tab and it handles 60-70% of basic questions without escalation.

Internationalization consideration

End-users are more likely to be non-English-speakers than developers are. Help centers often need translation (/fr/help, /es/help) before dev docs do. See internationalization for the setup.

Translation tips for help-center content specifically:

• Professional translation over MT — help content handles emotionally-sensitive topics (refunds, account issues). Machine translation errors here damage trust.

• Regional variations matter — "billing" and "invoicing" are the same to a US reader but different UX terms in some markets.

• Currency + dates — $29/month vs €29/month vs ¥3500/month; 04/20/2026 vs 20/04/2026.

Common help-center mistakes

Related

• Developer documentation — sibling guide for the dev audience

• Understand your audience — end-user personas

• Style and tone — voice patterns

• Accessibility — especially relevant for end-user content

• Internationalization — help content translation strategy

• AI assistant config — chatbot setup for support deflection