Create a help center

A help center lets customers solve problems without waiting for you. When they find the answer themselves, they get help faster, and your support team spends its time on the problems that actually need a person.

This guide covers building a help center with Reed: structuring it around customer problems, writing articles people can scan, and closing the loop with your support team.

What a help center on Reed is

Reed compiles docs.json and a directory of MDX into a static site that you host. For a help center, that gives you fast pages, built-in search that runs in the reader’s browser, and articles that live in git where every change is reviewed.

Much of what help-center platforms bundle is not part of Reed. Know this before you plan:

• No assistant. There is no question-answering chat on the page.
• No feedback widget. The footer of every page shows a static “Was this page helpful?” prompt, but it stores nothing. You collect feedback through a channel of your own.
• No analytics dashboard. Page views come from an analytics provider you configure. There is no report of search queries.
• No customer login and no personalized content. Everyone who can reach the site sees every page.
• No support-widget integration. docs.json cannot inject scripts, so a chat or ticket widget cannot be embedded. You link out to your support channel instead.

What Reed does give you is a site with no backend to run, and articles that are reviewed before they change. Everything below works within those limits. The roadmap lists what Reed does not do yet.

Start the project

Create a project with reed init. The default mint template scaffolds a developer-docs taxonomy — API reference, SDKs, MCP, Skills, Changelog — most of which a help center deletes. --template rapide or --template black scaffolds a two-page stub instead, which is a cleaner starting point. There is no help-center starter, so the structure in this guide is yours to build. The template also sets the site’s look, and you can switch it later by changing one field; see Templates.

sh

reed init --template rapide
reed prefetch
reed dev

The Quickstart explains each step.

Prerequisites

• Content for your most common support topics, or the tickets to write it from.
• A git repository for the help center.
• A domain and a static host. Any host that serves files works; see Deploy.

Migrate existing content

If you are starting from scratch, skip to planning the structure.

Audit what you have

• Help articles. Which topics do they cover? Which ones get read?
• FAQs. Which frequently asked questions deserve their own article?
• Support tickets. Which questions arrive again and again? Each one is an article that does not exist yet.
• Product documentation. Where do help articles and product docs overlap? Pick one home for each topic and link to it from the other.

Export your content

• Markdown is the simplest path. Most Markdown is valid MDX.
• HTML works when Markdown is not available. Convert it with a tool such as Pandoc and clean up the result.
• Ticket data, exported from your support tool, shows which questions to answer first.

Reed has no importer for help-center platforms. A migration is an export, a conversion and a review.

Plan your help center structure

Organize around customer problems, not product features. Customers arrive with a goal or a failure, not with the name of the module that caused it.

Read a month of support tickets before you draw the navigation. What customers actually ask about tells you what to write first and what to call it.

Give each section an overview page that lists its articles. Reed does not generate these listings, so the overview is a page you write. Name it index.mdx inside the section’s folder, and it takes the folder’s page id: content/account/index.mdx is the page account. List it first in its group:

json

{
  "navigation": {
    "tabs": [
      {
        "label": "Help",
        "groups": [
          {
            "label": "Get started",
            "pages": ["index", "getting-started/quick-setup", "getting-started/first-steps"]
          },
          {
            "label": "Account and billing",
            "pages": [
              "account",
              "account/billing",
              "account/plans",
              "account/team-members",
              "account/security"
            ]
          },
          {
            "label": "Using the product",
            "pages": ["product", "product/projects", "product/sharing", "product/integrations"]
          },
          {
            "label": "Troubleshooting",
            "pages": [
              "troubleshooting",
              "troubleshooting/login",
              "troubleshooting/connectivity",
              "troubleshooting/performance"
            ]
          }
        ]
      }
    ]
  }
}

On each overview page, a CardGroup gives customers a one-glance view of the section: one Card per article, with the article’s title, a one-line description of the problem it solves, and an href pointing at the article. Reed does not add your base to links you write, so on a site mounted at /help the card for the billing article carries href="/help/account/billing", not href="/account/billing". When you add an article, add its card too; nothing does it for you. How to link documentation pages effectively covers the base rule, and How to structure documentation navigation covers depth, labels and testing the structure with real customers.

Write effective support content

Every article should answer one question or solve one problem. When an article starts answering three, split it and group the pieces.

Structure articles for scanning

Customers scan for their specific issue. Use a heading per cause or task, short paragraphs, and the words customers use rather than your internal ones.

mdx

---
title: Fix sign-in problems
description: Troubleshoot the most common reasons you cannot sign in to your account.
---

## Reset your password

If you forgot your password, request a reset link from the sign-in page.

1. Go to the sign-in page.
2. Select **Forgot password**.
3. Enter your email address.
4. Open the reset link in the email we send you.

## Clear your browser cache

Old cached data can cause sign-in failures. Clear your cache and try again.

## Check your account status

A suspended or deactivated account shows an error at sign-in. Contact support if you think
this is a mistake.

The title is the page heading, so the body starts at ##. The headings give each cause an anchor that your support team can link straight to from a ticket reply.

Use numbered steps for tasks

When an article explains how to do something, number the steps. For a short sequence of prose steps, the Steps component makes progress visible:

1. Open Settings

   Select the gear icon in the toolbar.

2. Go to Billing

   Select Billing in the settings menu.

3. Update your payment method

   Select Update next to your current payment method and enter the new details.

Keep code blocks out of Step. If a step needs a command, use a plain numbered list or a numbered heading instead. Documentation content types has the reasoning.

Add screenshots where they confirm location

Screenshots help a customer confirm they are on the right screen. Keep the image file next to the article and reference it with a relative path:

mdx

![The Billing page with the payment method section highlighted](./images/billing-settings.png)

Every screenshot is a maintenance cost: it goes stale the day the screen is redesigned. Use them where they save real confusion, and write alt text that says what the image shows. See How to use images, screenshots and videos.

Route customers to your support team

A help center needs an exit for the questions it cannot answer. Reed cannot embed a chat or ticket widget, so make the exit a link.

Add your support channel to footer.columns in docs.json. It appears on every page:

json

{
  "footer": {
    "columns": [
      {
        "label": "Still stuck?",
        "links": [
          { "label": "Contact support", "url": "https://support.example.com/new-ticket" },
          { "label": "System status", "url": "https://status.example.com" }
        ]
      }
    ]
  }
}

Footer links must be http(s) URLs or root-relative paths. A mailto: link is rejected, so point at a web form or support portal.

On troubleshooting articles, repeat the exit at the bottom of the page, where a customer who has tried every step ends up:

Contact support

Tell us what you tried and what you saw. We reply within one business day.

Collect feedback

You need to know which articles help and which do not. Nothing on a Reed page records a rating or comment, so give customers a channel that does:

• A “Report a problem with this article” link in footer.columns, pointing at a form or your support portal.
• Your support team. When a ticket covers a topic the help center already answers, ask why the article did not work: it was hard to find, unclear, or incomplete.

Read every comment you receive. A report like “step 3 does not match my screen” is worth more than any number of ratings.

Measure how the help center is used

Configure one of the six analytics providers Reed supports. It gives you page views, and from them:

• Popular articles. Keep these accurate and easy to scan. They carry the most weight.
• Articles nobody reads. Improve how customers reach them, or remove them.
• Troubleshooting pages with heavy, sustained traffic. Often a product problem, not a documentation problem. Tell the team that owns the feature.

Search runs in the customer’s browser and records nothing, so you cannot see what customers searched for or which searches returned nothing. Your ticket volume is the closest substitute: every ticket on a covered topic is a search that failed. How to measure and improve documentation quality covers how to combine these signals.

Different content for different customers

Reed cannot show different articles to different customer segments. There is no login and no group-based access, so every article is visible to everyone who can reach the site.

Three honest options, in order of how often they are the right answer:

1. Publish everything, and label what applies to whom. State the plan at the top of the article, for example in a Note: “Single sign-on is available on the Enterprise plan.” Customers on other plans learn what upgrading would give them.
2. Keep genuinely private material out of the help center. Account-specific instructions belong in your product or your support replies.
3. Build a second site. If one segment truly needs its own content, build it as a separate Reed project and put it behind your own access control, such as an identity-aware proxy in front of the host.

Maintain your help center

Support content goes out of date every time the product changes.

1. Update articles with every release. Make the help-center change part of the release, in a pull request reviewed alongside the feature. Run reed check on it in CI.
2. Review feedback weekly. Act on reports of wrong or confusing content first. They point at the articles doing the most damage.
3. Watch your ticket queue. A ticket about a covered topic means the article failed. Find out why and fix it.
4. Remove what no longer applies. Delete articles about retired features, and add a redirect for any URL customers may have bookmarked or your team linked in old replies. Outdated articles cost customers’ trust in the rest.

How to maintain documentation over time goes deeper on ownership and on retiring pages.

Next steps

Once the help center is live:

1. Link to it from your product, your website and your support replies.
2. Watch page views and ticket topics for the gaps between them.
3. Read feedback weekly, and fix the specific, actionable reports first.
4. Track ticket volume on covered topics to see whether self-service is working.

A good help center lowers support cost and raises satisfaction at the same time. Spend your effort on the questions customers actually ask.