The Knowledge Base Article Builder turns a task description and a list of steps into a complete, well-structured help article. Good support documentation follows a predictable pattern so readers can self-serve fast: a summary that confirms the outcome, prerequisites, numbered steps with optional screenshots, a troubleshooting section, and links to related articles. The tool assembles exactly that from your inputs.
How it works
The builder maps your inputs onto the standard help-centre article skeleton:
- Summary and prerequisites. A short outcome statement plus anything the reader needs before starting (an account, a specific permission level, a connected integration, a browser requirement).
- Numbered steps with screenshot placeholders. Each step you enter is numbered in order, and a
[Screenshot: …]placeholder is inserted so you can drop in an image where it genuinely clarifies — and remove the placeholder where it doesn’t. - Troubleshooting and related links. Common errors with their fixes are listed to catch users where they get stuck, followed by links to adjacent articles so readers can keep going without filing a ticket.
What makes a KB article actually deflect tickets
Most support teams track “ticket deflection rate” — the proportion of users who read the article and resolve their issue without contacting support. Articles that deflect tickets share a few qualities:
The title matches what users type. Users search for their problem, not your feature name. “Why can’t I log in” deflects more than “Authentication FAQ”. The most effective titles start with “How to” or answer a direct question.
The summary passes the two-second test. In the first sentence or two, the reader needs to know whether they are in the right article. If the answer to their question is not here, they should be able to leave without reading more. A bad summary makes them read five steps only to discover it’s the wrong article.
Steps are atomic. One physical action per numbered step. The test: can the user complete this step without making any decision? If the step says “select your payment method and enter your card details”, split it into two steps. Long compound steps are where users drop off and email support.
Troubleshooting catches the top two failure modes. Most articles have one or two questions that cause 80% of follow-up tickets. Put those errors and their fixes explicitly before the “related articles” section. They do not need to cover every edge case — just the ones your support team sees repeatedly.
Tips for writing the steps
- Title the way users search. Write the title as the task in plain words — “How to reset your password” beats “Password management overview.”
- Front-load the outcome. The summary should say what the reader will have done by the end.
- Keep steps atomic. One action per numbered step. If a step contains the word “and,” it is probably two steps.
- Use present tense and active voice. “Click Save” is clearer than “The Save button should be clicked.”
- Screenshot only where it helps. Screenshots are valuable for unfamiliar UI; they add noise for obvious actions like clicking a button labelled “Save.”