Writing KB Articles People Can Actually Follow
The article is called "VPN Configuration Guidelines". It opens with two paragraphs about why the organisation uses a VPN, then says "configure the client as per standard settings". Then it has a screenshot of a window that no longer exists. The user who found it is sitting in a hotel at 23:10 trying to get into the file server before a morning meeting. The article has told them, in effect, that the VPN is important. They raise a ticket. The article has been "published" for three years and has helped nobody, and it is not an unusual article. It was written by someone who knew how to do the thing, for someone who did not, in the language of the person who knew.
This series is about the other kind of article, the kind a hurried stranger can follow at 23:10. It covers the anatomy of a followable article, from the title that is a question to the line that says what to do if it did not work. It covers one action per step, with the result after each. It covers screenshots that help and the ones that merely decorate. Then comes writing for the reader who is already frustrated. It covers testing articles on real users by handing one over and watching in silence. And it covers the review checklist an editor runs before anything is published. A knowledge article is a set of instructions for someone who is not there to ask. Write it as if they were standing beside you, and then test it as if they were not.
Articles in This Series
- The Anatomy of a Followable Article: Seven Parts in Order
Title as the question, who it is for, before you start, numbered steps, what you should see, if it did not work, who to contact. Includes one article shown badly and well, and the skeleton to copy. - Step-by-Step Clarity: One Action per Step
Exact wording of what to click or type, one action per step, the result line, the trap step everyone misses, no 'simply' or 'just', and the step-writing rules. - Screenshots That Help, and the Ones That Do Not
When a screenshot earns its place, cropping to what matters, one annotation, never sensitive data, the screenshot that goes stale, and the screenshot checklist. - Writing for the Reader Who Is Already Frustrated
The reader's state of mind, front-loading the fix, the escape hatch to a human, the calm tone, and the frustrated-reader checklist. - Testing Articles on Real Users: The Hallway Test
The hallway test, watching silently, fixing where they stalled, the three-user rule, testing on the real portal, and the test sheet. - The Article Review Checklist Before Publishing
The editor's pass over title, audience, steps, results, screenshots, links, owner and review date; the common failures; and the checklist itself.
Explore More Topics
This series is part of the QuerySolv helpdesk topic library. It covers the foundations, processes, communication, knowledge, tooling, metrics, classic ticket domains, people and strategy behind a support desk that works. The library pairs well with the software we build: QuerySolv. It is a self-hosted help desk that runs as one Windows service on your own network. It is licensed once per installation, not per agent per month.