The twelve knowledge base articles to write first

Most knowledge bases fail in the same way: somebody spends a fortnight writing thirty articles about the systems they find interesting, and the desk keeps answering the same six questions by hand.

Write these twelve first. They cover the bulk of repeat volume on almost every Indian IT desk we have seen, and each one takes twenty minutes.

The twelve

1. How to reset your password — including what to do when the reset email does not arrive.
2. Connecting to the VPN, with the three errors people actually get.
3. Setting up work email on a phone, for both Android and iPhone.
4. Printing: how to add the office printer, and what to try when it says offline.
5. My laptop is slow — the four checks to do before raising a ticket.
6. Enrolling in multi-factor authentication, and what to do when you change phone.
7. Requesting software: what is pre-approved, what needs a manager, and how long it takes.
8. Reporting a phishing email — the single most valuable article you will write.
9. What to do if your laptop is damaged, lost or stolen.
10. Getting access to a shared drive or folder.
11. What IT does and does not support, stated plainly.
12. How to escalate something urgent, and what counts as urgent.

Article eight deserves its place. A staff member who knows how to report a phishing message will report one, and an hour spent writing that article is worth more than the rest of the list combined on the day it matters.

Write them so people finish them

• Lead with the fix, not with background. Nobody arrives wanting context.
• Numbered steps, one action per step. If a step has an "and" in it, it is two steps.
• Use the words your staff use, not the vendor's. People search for "email on phone", not "Exchange ActiveSync configuration".
• Say what success looks like — "you should now see a green tick" — so people know when to stop.
• End with what to do if it did not work, and make that a link to raise a ticket.

Let the desk write the rest

After the first twelve, stop guessing. Two sources will tell you exactly what to write next:

Your resolved tickets. Any question you have answered three times is an article, and the answer is already written — it is in the last reply you sent. Turning a resolved ticket into a draft should be one click.

And the questions your self-service could not answer. If you run a chat assistant, every question it failed on is a gap, and that list is the most honest content backlog you will ever have — it is written by your users rather than by your assumptions.

Where to put them so they are found

A perfectly written article nobody finds has deflected nothing. In practice people reach an answer by one of three routes, and only one of them is a search box. The first is a link in a reply: when an agent answers a question that has an article, the reply should contain the link rather than a retyped answer — that single habit builds the audience faster than any launch announcement.

The second is the moment of raising a ticket. A subject line typed into the portal should surface matching articles before the form is submitted, which is the only point at which somebody is guaranteed to be paying attention. The third is search, and search only works if you have used your colleagues' vocabulary rather than the vendor's.

Announce the knowledge base exactly once, quietly, when the first twelve articles exist. A launch email for an empty knowledge base teaches four hundred people that there is nothing there, and you do not get that first impression back.

Keeping them true

Articles rot. A screenshot goes stale after a version upgrade, a menu moves, a policy changes and nobody tells the person who wrote the page. An article that is confidently wrong costs more than no article, because the reader follows it, fails, and then raises a ticket in a worse mood than if they had started there.

• Give every article an owner — a person, not a team. Unowned pages are nobody's to fix.
• Review the top ten by views every quarter. Ignore the rest until somebody complains.
• Put the last-reviewed date on the page. Readers calibrate their trust with it, correctly.
• When a system changes, search the knowledge base before you announce the change, not after.
• Retire rather than rewrite when a thing no longer exists. A tombstone page that says so beats a page that quietly describes a system you switched off last year.

Measure whether it is working

Two numbers, neither of which is "articles published". Views per article tells you what people look for. Tickets raised in categories you have covered tells you whether the articles actually work — if you have a good password article and password tickets have not moved, the article is not being found, and that is a navigation problem rather than a writing one.

Put a helpful / not-helpful control on every article and read the comments. People are specific and often blunt, and a page that keeps getting "no" is telling you something worth knowing.

Guided walkthroughs that hand off to a pre-filled ticket, drafts mined from resolved tickets, and a gap list written by your own users. See the knowledge base