Help Center Grader

The scoring rubric

26 checks worth 100 points: 60 for customer experience and 40 for AI and agent readiness. Customer-experience checks are our own. AI checks use the thresholds of the open AFDocs standard where it sets them.

A check we can't test on a help center, for example because it blocks our requests, never costs points: the score is out of the points we could test, and the report says how many that was.

Customer experience 60 points

Can a person find an answer without contacting support?

  • CX1Search returns something for common questions10 pts

    Search quality · critical priority

    We write one search per article we read, the way a customer would type it, and run it on your help center's own search. Counts the searches that return anything.

  • CX2Search finds answers that already exist9 pts

    Search quality · high priority

    Of those searches, how many bring up the article that answers them in the first ten results.

  • CX4Search is present and reachable3 pts

    Search quality · low priority

    A search box on your help center's home page and on its articles.

  • CX7A contact route exists3 pts

    Answer coverage · low priority

    A contact link, an email address or a chat widget on the pages we read.

  • CX8Articles updated within 18 months7 pts

    Content freshness · high priority

    Of the articles we can date, from the page or your sitemap, the share updated in the last 18 months.

  • CX10Last updated date visible to readers2 pts

    Content freshness · low priority

    A date readers can see on the article.

  • CX18No broken links or images3 pts

    Content freshness · medium priority

    Up to 30 links and images in the articles we read that point to your own site, and how many answer that they're gone (404 or 410). One that blocks us or fails doesn't count either way.

  • CX11Articles are in the sitemap3 pts

    Findability · medium priority

    Of the articles your pages link to, the share your sitemap lists.

  • CX13No accidental noindex2 pts

    Findability · low priority

    Articles without a noindex tag or header.

  • CX14Pages have a title and a description1 pt

    Page health · low priority

    Articles with a page title and a meta description, which search results show.

  • CX15One main heading per article1 pt

    Page health · low priority

    Articles with exactly one main heading (h1).

  • CX16Pages are set up for phones2 pts

    Page health · medium priority

    Articles with a viewport tag set to width=device-width, so phones show them at their own size.

  • CX17Images have alt text1 pt

    Page health · low priority

    Of the images in the articles we read, the share with alt text. An empty alt counts, since it marks an image as decoration.

  • CX19Pages respond quickly3 pts

    Speed · medium priority

    How long the median article takes to start answering: 1 second or less passes, up to 2.5 seconds warns.

  • CX20The title states the task or the question2 pts

    Writing quality · medium priority

    Up to 10 of the articles we read go to an AI model with a fixed checklist. A title passes when it names a task or a question, like "Reset your password", and fails when it's only a topic, like "Passwords". A rescan of articles that haven't changed keeps the same verdicts.

  • CX21The answer comes in the first paragraph or two3 pts

    Writing quality · high priority

    Whether the first one or two paragraphs give the answer or start the task, before any background.

  • CX22Steps are a numbered list, one action per step2 pts

    Writing quality · medium priority

    Of the articles that walk the reader through a task, the share that number the steps and keep one action in each. Articles with no steps don't count either way.

  • CX23Headings let a reader scan to the part they need1 pt

    Writing quality · low priority

    Of the articles long enough to need sections, the share whose headings let a reader jump to the part they need. Short articles don't count either way.

  • CX24Sentences are plain and short enough to follow2 pts

    Writing quality · medium priority

    Whether a customer can follow the sentences on a first read, with any jargon explained.

AI and agent readiness 40 points

Can AI assistants and crawlers read your docs?

  • AI1AI crawlers are allowed12 pts

    AI crawler access · critical priority

    Whether your robots.txt lets GPTBot, ClaudeBot, PerplexityBot and the other major AI crawlers read your help center.

  • AI2Articles reachable without a login9 pts

    AI crawler access · high priority

    Articles that open without asking for a login.

  • AI3Content is server rendered9 pts

    Machine-readable content · critical priority

    Pages whose content is in the HTML as sent, before any JavaScript runs (AFDocs rendering-strategy).

  • AI4llms.txt is present and valid3 pts

    Machine-readable content · medium priority

    An llms.txt with a title and links, under 50,000 characters (AFDocs llms-txt checks).

  • AI5Pages fit within context limits2 pts

    Machine-readable content · low priority

    Pages under 50,000 characters of text and 1 MB to download (AFDocs page-size checks).

  • AI8Articles carry structured data3 pts

    Machine-readable content · medium priority

    Articles with at least one JSON-LD block that parses, in the HTML as sent.

  • AI9Articles are available as Markdown2 pts

    Machine-readable content · low priority

    Two of the articles we read, asked for at their address with .md added and with an Accept: text/markdown header. Either one answering Markdown or plain text passes.

Checks we're building

These aren't scored yet. Each one joins the rubric when a scan can run it.

  • Search handles wording variations

    The same question asked in different words.

  • Core support topics have an article

    Articles for the topics customers ask about most.

  • Coverage is balanced across categories

    No category much thinner than the rest.

  • No orphan articles

    Articles nothing on your help center links to.

  • AI answers correctly from your documentation

    Questions your docs answer, put to AI assistants, and whether they get them right.

  • AI cites your site rather than a competitor

    Whether those answers point to your documentation.

Grades

  • A 85 and above · Excellent
  • B 70 and above · Good
  • C 55 and above · Improving
  • D 40 and above · Needs work
  • F below 40 · Needs work

Each check passes from 85% of its points and warns from 50%. A scan that couldn't test more than 30 of the 100 points is partial: it still gets a score, based on what we could measure, but it stays out of the leaderboard and any comparison.

Grade your help center