Help-Centre Article

A help article succeeds when a customer finds it with their own words, follows it without help, and does not need to write in. You write articles from what customers actually ask, test every step in the real product, and measure whether tickets on that topic go down. The standard: titles match how customers search, one article does one job, every step is verified on today's product, and each article has an owner and a review date.

When to use

• "Write a help article about changing billing details."
• "Turn our top 10 ticket topics into FAQs."
• "Our docs are out of date since the redesign; fix them."
• "Customers can't find how to export data."
• A support teammate flags a question that keeps coming in.

What you need

• Ticket data for the topic: the customer messages (their words), the replies that solved it, volume per month. From the helpdesk as a connected app (Intercom, Zendesk, Front) or an export.
• Access to the product to verify steps and take screenshots: the owner's signed-in browser or a test account.
• The help centre platform (connected app or the owner's browser) and its existing style: articles, categories, formatting.
• Search data if available: the help centre's own search terms, and searches that returned no results.

Method

1. Pick topics by evidence. With execute_code, rank ticket reasons by monthly volume and by how answerable they are in writing (how-to questions and known fixes are; account-specific problems are not).
   • Check whether an article already exists.
   • If it does and tickets continue, the article is the problem: wrong title, wrong words, out of date, or too long.
2. Collect the customer's words. From 10 or more tickets, list the phrases customers use ("change my card", "update payment", "new credit card"). The title and first lines must use these, not internal product names.
3. Choose the article type. One job per article:
   • Task (how-to): one goal, numbered steps. The title starts with a verb: "Change the card you pay with".
   • Troubleshooting: a symptom, its likely causes, and fixes in order of likelihood. The title states the symptom: "Payment declined when renewing".
   • Reference: facts to look up (limits, settings, supported formats), in tables.
   • Explanation: how something works and why (billing cycles, permissions). Short, with an example.
   • FAQ: only for genuinely short questions with short answers; each answer links to a full article where there is more to say. A FAQ page should not become the place real documentation hides.
4. Write to the template in references/article-templates.md:
   • The first sentence says who this is for and what they will achieve. Then the prerequisites (plan, role, permissions).
   • Steps: one action per step, starting with the verb; exact UI labels in bold as they appear on screen; the location before the action ("In Settings, click Billing"); the expected result after key steps.
   • Short sentences, active voice, "you", one term per concept used consistently, terms defined on first use. Lists and tables instead of long paragraphs.
   • End with what to do if it did not work, and related articles.
5. Verify by doing. Follow every step yourself in the product, on the plan and role the article states, in a clean session, and record the date. If the product does not match what support has been telling customers, report the mismatch to the owner before publishing.
6. Screenshots.
   • Use them where the location of something is hard to describe.
   • Crop to the relevant area and highlight the target.
   • Redact any personal or customer data, and check the result with vision_analyze before saving.
   • Add alt text that says what the image shows. Screenshots go stale fastest: use few, and keep the text complete without them.
7. Make it findable. A title in the customer's words; a one-sentence summary that also works as the search snippet; the keywords or synonyms field if the platform has one; links from related articles and from the macro for that topic.
8. Accessibility. Headings in order, descriptive link text (not "click here"), alt text on every image, and no instructions that rely only on colour or position.
9. Approval and publishing. Show the draft to the owner, or the topic owner they name. Publish through the connected app or the browser only after approval. Record the owner, verified date and review date.
10. Measure. After 30 days, compare:
    • ticket volume for the topic against the 30 days before (allowing for seasonality and overall volume change);
    • article views and helpfulness votes;
    • searches that still return nothing. If tickets are not falling, read the new tickets on the topic and fix the gap.
11. Maintain. Review each article at least every 6 months and whenever its product area changes; use cronjob for reminders. Retire or redirect articles about removed features rather than leaving them live.

Article, macro or fix?

What the tickets show	Best answer
Customers cannot find or follow a task	A help article (this skill)
The answer depends on the customer's account	A saved reply for agents (support-macros), not an article
The product itself confuses everyone at the same step	An article now, and the step reported to product as a usability problem
Policy or money decisions	Neither; the owner decides, then document the policy

Worked example: from tickets to an article

• Tickets: 34 in September about paying with a new card. Customer words: "update card" (14), "change payment" (9), "new credit card" (6), "card expired" (5).
• Existing article: "Managing your billing settings", 900 words covering six tasks. Searches for "update card" return it in fourth place.
• Decision: split out a task article titled Update the card you pay with, synonyms "change payment method, new credit card, card expired", and a short troubleshooting article Card declined when updating.
• Verified on the Business plan as an admin, 5 October; one screenshot of the Payment method panel, redacted.
• After 30 days: 11 tickets on the topic (from 34), searches for "update card" now return the new article first.

Output

• The article draft in the platform's format: title, summary, body, screenshots (redacted, with alt text), related links, owner, verified date and review date.
• For a batch: a topic table (topic, monthly tickets, existing article, action, priority) and drafts in priority order.
• After 30 days: a short impact note per article.

Checks before you finish

• The title uses the customer's own words; the first sentence says who it is for and what they will achieve.
• Every step was followed in the product on the stated plan and role, with the date recorded.
• UI labels match the screen exactly.
• Screenshots contain no personal or customer data and have alt text.
• One article, one job; FAQs link to full articles where needed.
• The owner approved before publishing.

Pitfalls

• Writing in the company's vocabulary. Customers search "cancel", not "subscription lifecycle management".
• Untested steps. One wrong button name and the customer writes in anyway, now annoyed.
• The everything article. Ten tasks in one page means nobody finds theirs. Split.
• Screenshot-only instructions. They break with every redesign and fail screen-reader users.
• Publish and forget. An out-of-date article is worse than none. Owners and review dates are part of the article.

See also: support-macros, support-ticket-reply, product-feedback-loop.