knowledge_base_writing v1.0.0

name: "knowledge_base_writing" description: "Write a help center people can actually use: mine support tickets and failed searches for the real questions, structure articles with templates for how-to, troubleshooting, and FAQ jobs, write search-friendly titles in reader language, use screenshots correctly, and run a staleness audit that retires or refreshes dead articles. Use when building or fixing a knowledge base, help center, support docs, or self-service content, or when ticket volume repeats the same questions."

Knowledge Base Writing

Purpose

Build self-service help that solves the problem without a ticket. A good article is found by search, understood in one pass, and still true three months later. Most knowledge bases fail on one of those three, not on writing quality. This skill fixes findability first, then structure, then freshness.

The method is based on Knowledge Centered Service (KCS) from the Consortium for Service Innovation, Zendesk help center guidance, Nielsen Norman Group help and documentation guidance, and the Google developer documentation style guide for images. Full source notes are kept by the publisher. Apply the workflow in order. Do not start by writing articles from a product feature list.

Workflow

1. Mine tickets and searches before you write anything

Never guess the article list. Pull evidence from three places for the last 90 days:

• Support tickets: export subject, first customer message, category, and resolution. Group by the job the customer was trying to do, not by internal product area.
• Help center search logs: list the top searches, searches with no results, and searches with results but no clicks.
• Tickets created after viewing an article: these name the articles that looked right and still failed.

Score each candidate topic with the rules in references/ticket-mining-and-search.md. In short: frequency times pain. A topic that appears 40 times with a 10 minute agent fix outranks a topic that appears 4 times with a 2 hour fix, unless the rare one involves money, data loss, safety, or a blocked account.

Write the reader words down verbatim for each topic. Ticket subjects and search queries are your title bank. If customers type "cancel plan" and your article says "subscription termination procedure", search will lose and so will the reader.

Output of this step: a ranked backlog table with topic, reader phrase, ticket count, failed search count, existing article if any, and decision: write new, fix existing, add label or synonym, merge, or do nothing. Do not skip the "fix existing" column. Duplicates are the most common cause of bad search results.

2. Pick the article type before drafting

One article, one job, one type:

• How-to: reader wants to complete a task. Numbered steps, one action per step, prerequisites first.
• Troubleshooting: reader has a symptom and wants a fix. Symptom, likely causes in order, check and fix pairs, what to do if none of it works.
• Concept or policy: reader needs to understand a rule, limit, price, or decision before acting. Short answer first, then detail, then examples.
• FAQ collection: only for a set of short, related questions with one to three sentence answers and no steps. If an answer needs steps, it graduates to its own how-to article and the FAQ links to it.

If a draft mixes two types, split it. A how-to buried inside a policy article is found by neither search.

Use the templates in references/article-templates.md exactly for headings and order. Consistent structure is part of findability: readers and search both learn where the answer lives.

3. Write the title and opening first

Title rules:

• Use the reader phrase from step 1, in sentence case, as a task or a problem. Good: "Reset your password". Good: "Invoices show the wrong total". Bad: "Password management overview". Bad: "Understanding invoice functionality".
• Put the distinctive word early. "Export a report as CSV" beats "How to use the reporting export feature to get a CSV".
• One topic per title. If the title needs "and", you probably have two articles.
• Match the title to the search label set: add the synonyms, verb forms, and common misspellings readers use as labels, tags, or a "People also search for" line, depending on the platform. Do not stuff the title itself with synonyms.

Opening rules, first three lines:

• Line 1 restates the outcome in one sentence: what the reader will have done or understood by the end.
• Next, prerequisites and limits: account type, plan, permission, version, or platform, only if they change the steps.
• Then the steps or the short answer. No history, no product pitch, no "Welcome to our knowledge base" text above the answer.

4. Draft for scanning, then for reading

• Headings in sentence case, in the order the reader needs them, worded as tasks or questions where that helps scanning.
• Numbered lists for steps in order, bullets for options with no order. One action per step, verb first, UI element in bold on first mention per section.
• Keep paragraphs short. Put conditions before actions: "If you are an admin, select..." not "Select X if you are an admin".
• Use the reader word first, then the product name in brackets once if the two differ. After that, use the product name consistently.
• End every how-to and troubleshooting article with: how to tell it worked, what to do next, and a specific contact path if it did not work. "Contact support" alone is not a path. Name the channel and what to include, for example the error text and the steps already tried.
• Add related article links by job, not by category. Link to the next task the reader is likely to do, and to the troubleshooting article for this task.

5. Use screenshots and images only where they earn their place

Follow the Google style guide pattern:

• Add an image only when it explains something that is hard in words: where a control sits, what a correct result looks like, how parts relate.
• Never use a screenshot for code, a command, error text, or anything the reader needs to copy. Give that as text.
• Introduce the image with a sentence that ends with a colon or period, crop to the relevant area, and remove real customer data, names, balances, and tokens before capture. Use sample data and say so in the caption if the values could be mistaken for real ones.
• Write concise alt text that says what the image shows for this article. Use empty alt for a purely decorative image. For a complex diagram, keep alt short and put the full explanation in the text around it.
• Retake screenshots when the UI label in the image no longer matches the label in the steps. A mismatched screenshot is worse than none, because the reader assumes they are in the wrong place.

6. Verify before publishing

Run this check on every article, no exceptions:

1. Reproduce the steps on a clean account or in the current product version. Do not publish steps taken from a ticket resolution without testing them. Ticket resolutions often skip the step the agent assumed.
2. Search test: search the help center with the top three reader phrases from step 1. The article must appear in the first three results for at least two of them. If it does not, fix title, opening line, and labels before touching anything else.
3. Fresh reader test where possible: give a person who did not write it the problem statement only. Time how long they take to finish. Any step where they pause and reread gets rewritten in this pass.
4. Link check: every link resolves, every linked article still describes the same UI, no link points to a draft.
5. Record metadata: owner, date last verified, product version or plan it was verified on, source ticket or search evidence. An article with no owner and no verified date is already stale, it just has not been caught yet.

7. Publish, link from the product, and close the loop

• Link the article from the place the problem happens: the error message, the empty state, the settings page, and the agent macro for that ticket type. Help that is only reachable from the help center homepage will be underused.
• When an agent uses an article to solve a ticket, link the article to the ticket record if the tool allows it. That use count is your best quality signal later.
• Apply the KCS habit in daily support work, summarised as: use it, flag it, fix it, add it. Search the base before solving from scratch. If the article is wrong, fix it in the moment if it is a small correction and you have permission, flag it with a specific comment if you do not. If no article exists and the issue will recur, draft it from the ticket before closing the topic.
• Never publish a duplicate to avoid editing an existing article. Edit, merge, or redirect the old one.

8. Run the staleness audit on a fixed cadence

Run the audit monthly for high traffic bases, quarterly at minimum. Full method in references/staleness-audit.md. Use the checker to do the mechanical part:

python3 scripts/kb_audit.py --csv articles.csv --today 2026-10-15
python3 scripts/kb_audit.py --csv articles.csv --today 2026-10-15 --json
python3 scripts/kb_audit.py --csv articles.csv --fail-on-stale

The CSV needs: slug, title, owner, last_verified (YYYY-MM-DD), views_90d, helpful_yes, helpful_no, tickets_after_view. The script flags overdue reviews by traffic tier, low helpfulness with enough votes to mean something, and articles that send readers on to tickets. It does not decide the fix. For each flagged article choose one: reverify (test steps, update date), rewrite (structure or title problem), merge (duplicate), redirect, or retire (product or policy gone, no replacement). Retiring without a redirect breaks bookmarks, agent macros, and links inside the product, so search for inbound links first.

Signals that trigger an out of cycle review, regardless of date: a product release that renames a feature or moves a setting, a pricing or policy change, a spike in tickets after view for that article, or a run of "not helpful" votes.

Output Contract

A finished piece of work from this skill delivers:

• For a new base or a backlog pass: the ranked backlog table from step 1, with a decision for every topic in the top set, not just new articles.
• For a single article: title in reader language, correct type template fully filled, tested steps, screenshot and alt text decisions stated, metadata with owner and verified date, and labels or synonyms added.
• For an audit: the checker output plus a decision per flagged article (reverify, rewrite, merge, redirect, retire) with an owner and a date. A list of stale articles with no decisions is not an audit.
• Search test results for the top reader phrases, recorded with the article.

Operating Rules

1. Every claim about how the product works comes from testing it or from a primary source such as official product docs or the ticket resolution that was retested. Never copy steps from release notes or a chat answer without reproducing them.
2. Reader language wins over internal language in titles, headings, and the first mention. Internal names go second, once, for mapping.
3. One article, one job. Split mixed articles, merge duplicate articles, and keep one canonical answer per problem.
4. No article ships without an owner and a last verified date.
5. Do not invent deflection numbers, satisfaction scores, or time saved. Report only metrics the search and ticket tools actually recorded, and name the period.
6. Screenshots never contain real customer data. Sample data only.
7. If evidence is thin (few tickets, no search data, new product), say so in the backlog and write the smallest set of articles that covers the known jobs. Mark them for early review at 30 days instead of pretending the evidence was strong.
8. Keep SKILL.md level detail here. Templates, mining rules, and audit thresholds live in references/ so they can be updated without rewriting the workflow.