Help Center DoctorZendesk help center audit checklist: 34 checks
The checks a knowledge manager runs before a launch, a migration or a quarterly review, written so you can do each one by hand in Guide or with the API. Print this page and tick the boxes; or run the same 34 checks automatically with the free scan of Help Center Doctor and fix them from the findings list.
How to use it
Work one group at a time. For each check the entry says why it matters to a reader, how to find the cases by hand (Guide menu or API field), and the usual fix. Severity is what we assign in the scan: critical sends readers to a dead end, warning costs trust or time, info is worth a look when you are already editing. A help center with no critical findings and fewer than one warning per ten articles is in good shape.
By hand, the raw material is the article list with translations: GET /api/v2/help_center/articles.json?include=translations (and /incremental/articles.json for what changed since a date). Most checks below are a question about those fields or about the links in body.
Links 9 checks
Nine checks on every link in every translation. By hand: extract the href attributes from each body, resolve internal ones against the article, section and category lists (an archived target still returns a page, so compare ids, not HTTP status), and request the external ones with a short timeout. Anchors (#heading) need the target article body to confirm the id exists.
-
1. Link to an article that no longer exists critical
Readers who click this link land on a "page not found" error. The target article was archived, deleted, or the id in the URL is wrong.
Fix: Point the link to the right article (use the suggestions), or remove the link and keep the text.
-
2. Link to a section or category that no longer exists critical
The section or category behind this link has been removed, so readers get an error page.
Fix: Link to the section or category that replaced it, or remove the link.
-
3. Link to an unpublished (draft) article warning
The target is a draft, so visitors cannot open it: they see a "page not found" error until it is published.
Fix: Publish the target article, or remove the link until it is ready.
-
4. Link to an article with narrower visibility warning
The target article is restricted to a user segment that readers of this article may not belong to. Those readers get an access error.
Fix: Give both articles the same visibility, or mention in the text that the linked page needs sign-in.
-
5. Link to a heading that does not exist warning
The link points to an anchor (#something) that is not defined in the target article, so the page opens at the top instead of the promised place.
Fix: Add an id to the target heading, or update the anchor in the link.
-
6. Link to an old help center address warning
These links point at a domain you listed as retired (for example a previous subdomain or host mapping). They may redirect today, but redirects are slow, break anchors, and disappear when the old domain lapses.
Fix: Use Find and Replace to swap the old host for the current one in every article at once.
-
7. Insecure HTTP link or image info
Plain http links trigger browser warnings and http images are blocked as mixed content on a secure help center, so they simply do not show.
Fix: Change plain HTTP links to HTTPS when the destination supports it (most do). The Fix Center can upgrade them in bulk.
-
8. Broken external link critical
The website behind this link answered "not found" (404/410). Readers hit a dead end and lose trust in the article.
Fix: Find the new location of the page and update the link, or remove it.
-
9. External link could not be verified info
The site did not give a clear answer (timeout, login wall, bot protection or a server error). The link may be fine; it just needs a human look.
Fix: Open the link in your browser. If it works, add the site to the skip list so it is not checked again.
Images 2 checks
By hand: list img src attributes, request each one, and note the file size from the response headers. Attachments of archived articles are the usual broken ones.
-
10. Broken image critical
The image file cannot be loaded (the server answered "not found"), so readers see an empty box or a broken-image icon.
Fix: Upload the image again in the article editor, or remove the image tag.
-
11. Very large image info
Images wider than about 2,000 pixels are scaled down by the browser anyway; they only slow the page, especially on mobile.
Fix: Resize or compress the image before uploading (1,600 px wide is plenty for screenshots).
Accessibility 3 checks
By hand: in each body look for img tags without a non-empty alt, tables without a thead or th cells, and heading tags that skip a level (h2 followed by h4). Screen readers and search engines read the same markup.
-
12. Image without alt text warning
Screen readers announce nothing useful for an image without alt text, and search engines cannot index it. It is also a WCAG requirement.
Fix: Describe what the image shows in one short sentence. Decorative images can use an empty alt.
-
13. Heading levels are out of order info
The article title is already the H1. Bodies that start with H1, or jump from H2 to H4, confuse screen readers and the automatic table of contents.
Fix: Use H2 for main sections and H3 inside them; do not use H1 in the body.
-
14. Table without a header row warning
Screen readers rely on header cells (th) to tell users what each column means. Tables built from plain cells only are read as a stream of words.
Fix: Mark the first row as a header row in the editor (Table > Header row).
Stale content 4 checks
By hand: compare edited_at with today, check draft articles that were created long ago, and read the vote_sum and vote_count fields. Set your own thresholds; ours default to 12 months for edits and 90 days for drafts.
-
15. Article not updated for a long time warning
Content that has not been touched in a long time is the most likely to describe old screens, prices or policies. Readers notice, and so do search engines.
Fix: Review the article. If it is still correct, make a small edit (for example the date) so it counts as reviewed; otherwise update or archive it.
-
16. Old draft never published info
Drafts that sit for months are usually forgotten work. They clutter the article list and may hold useful content nobody can see.
Fix: Finish and publish it, or archive it.
-
17. Promoted article is stale warning
Promoted articles are shown first in their section, so a stale one is the most visible outdated content you have.
Fix: Refresh it, or remove the promotion so a current article takes its place.
-
18. Readers vote this article down warning
More thumbs-down than thumbs-up is the clearest signal readers have that an article does not solve their problem.
Fix: Read the article as a customer would; check it answers the question in the title and that the steps still work.
Structure 6 checks
By hand: read the body length, count headings against the length, search for style= attributes and script or form tags, and look at title lengths in the article list. These are the checks a quick skim misses.
-
19. Empty article critical
A published article with no content is a dead end that still shows up in search results.
Fix: Write the content, or archive the article.
-
20. Very short article warning
Articles with only a sentence or two rarely answer the question fully and tend to collect negative votes.
Fix: Add the missing steps or context, or merge it into a related article.
-
21. Long article without headings info
Long articles without H2/H3 headings are hard to scan, and anchors cannot be linked to. Headings also feed the article table of contents.
Fix: Split the content into sections with H2 headings (and H3 for sub-steps).
-
22. Heavy use of inline styles info
Inline style attributes (usually pasted from Word or Google Docs) override your theme, break dark mode and mobile layouts, and bloat the article.
Fix: Paste as plain text and re-apply formatting with the editor, or clean the source in the editor code view.
-
23. Script or form embedded in the article warning
Scripts and forms inside article bodies are stripped or blocked by most help center themes and browsers, and are a security smell in shared content.
Fix: Remove the embedded code; use a supported embed (video, image) or link to the tool instead.
-
24. Title is very long info
Long titles get cut off in search results and section lists, so readers cannot tell articles apart.
Fix: Keep titles under about 70 characters and put the detail in the first paragraph.
Organization 6 checks
By hand: sort the article list by title to find duplicates and near duplicates, list label_names, and compare each section and category with its published article count.
-
25. Two articles share the same title warning
Identical titles compete in search and confuse readers and agents about which one is current.
Fix: Merge the articles, or make each title specific (add the product or the situation).
-
26. Two articles have nearly the same title info
Titles that differ by a word or two usually mean the same topic was written twice. Readers pick one at random.
Fix: Compare the two articles; merge them or make the titles clearly different.
-
27. Article has no labels info
Labels power help center search, Answer Bot and article recommendations. Unlabelled articles are found less often.
Fix: Add two or three labels that describe the product area and the task. Bulk actions can label many articles at once.
-
28. Section with no published articles warning
Empty sections still appear in navigation and search, leading readers to a page with nothing on it.
Fix: Move articles into it, or delete the section.
-
29. Category with a single section info
A category that only holds one section adds a click without adding structure. Readers navigate faster when categories group several sections.
Fix: Merge the category into another one, or split the section if it has grown large.
-
30. Article in a section that no longer exists critical
The article points at a section that was deleted, so it cannot be reached from navigation.
Fix: Move the article to an existing section.
Translations 4 checks
By hand: for each article compare the set of translations with the locales enabled in the help center, read outdated and draft on each translation, and check that source_locale is one of the enabled locales.
-
31. Article missing in some languages warning
Your help center is enabled in several languages, but this article exists only in some of them. Visitors in the other languages get the fallback or nothing.
Fix: Add the missing translations, or hide the article from those languages if it does not apply.
-
32. Translation is out of date warning
The source article changed after this translation was written, so readers in this language see old instructions.
Fix: Update the translation, then mark it as current. If the change was cosmetic, just mark it current.
-
33. Translation is unpublished while the source is live info
The article is published in its source language but this translation is still a draft, so visitors in that language cannot read it.
Fix: Publish the translation when it is ready.
-
34. Source language is not one of the enabled languages info
The article was written in a language your help center no longer offers, so its "source" version is invisible and every translation is compared against it.
Fix: Change the source language of the article in the editor, or re-enable that language.
Do it automatically
Help Center Doctor runs all 34 checks on every article and language in a minute or two, from inside Zendesk, with your own permissions and without anything leaving the account. The Free plan scans up to 200 articles and checks external links; Pro ($29 per account per month) adds one-click and bulk fixes, find and replace, bulk actions and documents. The free Link Checker covers the links and images groups on its own.
Related guides: finding broken links, find and replace across articles, bulk update beyond the page limit, export articles to PDF and Word.
Run the 34 checks on sample data
The demo runs the real scanner on a generated help center with planted problems. See the findings, the explanations and the fixes.