Knowledge Base Article Checklist
A knowledge base article checklist for help center writers: a searchable title, one task per article, tested steps, current screenshots, links and an owner.
- Typical schedule per article
- The checklist 4 sections, 17 items
- Variables
{{article_title}}
Use this checklist before you publish a new help center article or a major update to an existing one. It suits support teams who write their own documentation, often between tickets, and want every article to be findable, correct and easy to follow. Run it for each article, including quick ones: short articles are the ones most likely to skip a test.
Who owns it
The writer owns the run, usually a support agent who has answered the question many times. A second person checks the steps on a real account. That can be another agent or someone from product. The support lead or a documentation owner decides when the article goes live.
Common pitfalls
- Titles in internal language. Customers search for "can't log in", not "SSO authentication failure". Use the words from real tickets.
- Several tasks in one article. An article that covers setup, billing and troubleshooting answers none of them well. One task or question per article, with links to the rest.
- Steps that were never tested. Write the steps, then follow them on a fresh account exactly as written. Menus and labels drift.
- Screenshots that go stale. Every screenshot is a future maintenance task. Use them where they help, crop them tightly, and avoid showing real customer data.
- No owner and no review date. Articles without an owner rot silently. Record one, plus a date to check the article again.
Many teams pair this with a recurring knowledge base review, so older articles are checked on a schedule rather than when a customer complains.
The checklist: Publish help article: {{article_title}}
Before writing
-
Real tickets or search terms collected for the question "
{{article_title}}" answers -
Existing articles searched, so this does not duplicate or contradict one
-
Scope limited to one task or one question
Write
-
Title uses the customer's words and starts with the task or the problem
-
First paragraph says who the article is for and what it achieves
-
Steps numbered, one action per step, with exact button and menu labels
-
Prerequisites listed: plan, role or permissions needed
-
Expected result described, so the reader knows the steps worked
-
Troubleshooting section for the common ways it goes wrong optional
Check
-
Steps followed exactly as written on a test account by a second person
-
Screenshots current, cropped, and free of real customer data optional
-
Links to related articles added and tested
-
Spelling, formatting and terms checked against the style guide
Publish
-
Article tagged and placed in the right category
-
Owner and next review date recorded
-
Macros and saved replies updated to link to the article
-
Translations requested for supported languages optional
Checklist as Markdown
Frequently asked questions
How do I write a good knowledge base article?
Start from real customer questions and use their words in the title. Cover one task per article, number the steps, and describe the expected result. Then test the steps on a real account before you publish.
How long should a help center article be?
As long as the task needs and no longer. Many good articles are a short introduction and a handful of steps. If an article keeps growing, it probably covers more than one task and should be split.
How often should knowledge base articles be reviewed?
Review an article whenever the related feature changes, and otherwise on a fixed schedule, such as every six or twelve months. Give each article an owner and a review date. Articles that are often linked in tickets deserve more frequent checks.
Updated