Authoring knowledge base articles

Writing a good knowledge base article

A great KB article saves you from answering the same question for the third time. A bad one wastes someone’s afternoon and they file a ticket anyway.

When to write one

Write a KB article when you’ve answered the same question more than twice in a month. Not before — you’ll waste effort speculating; not after — you’ll have already wasted effort answering it manually.

Cues that an article is overdue:

• You’re typing the same five-paragraph reply from a saved template
• The same ticket subject keeps coming back from different requesters
• A manager is sending people to ask you in person because there’s nowhere to point them

Structure that works

Open with the answer, not the context. Most readers landed here looking for one specific thing.

# How do I reset my school password?

Visit https://login.wyverntrust.org.uk and click "Forgot password".
You'll get an email with a reset link.

## If you didn't get the email
- Check your spam folder
- Confirm you typed the right address
- Contact IT — your account may be locked

Three sections, one screen tall. The reader gets the answer in 5 seconds.

What not to write

• Anything that changes weekly — KB articles don’t get reviewed often. If the answer depends on Term 2’s timetable, it’s wrong by Term 3.
• Anything that’s a workaround for a bug — fix the bug. Don’t immortalise the workaround.
• Anything in a screenshot you can’t easily replace — the UI moves. Use words.
• Two articles for the same thing — pick a slug, redirect any duplicates.

Audiences

Mark the article’s audience honestly:

• all — anyone can read it (most articles)
• requester — only shown in the Portal help (e.g. “How do I raise a ticket?”)
• agent — only shown in the Agent help (e.g. “How to handle a phishing report”)
• admin — only shown in the Admin help drawer (e.g. “How to add a new ticket type”)

The wrong audience is the article’s most common bug — a Portal user landing on agent-shop talk gets confused fast.

Search-friendly titles

Title your article the way someone would ask the question, not the way IT would describe it.

• ✅ “My laptop is slow”
• ❌ “Performance troubleshooting workflow v2”

Then put the alternate phrasings in the body — the search index reads everything.

Linking to forms

Link the article to the relevant ticket template or catalogue item. “Still stuck? Raise a printer ticket” — gives the reader an out without leaving the article.

Reviewing & retiring

Articles record thumbs-up and thumbs-down votes from readers. Keep an eye on the hit and vote counts in the solutions index — articles with a high thumbs-down rate warrant a review.

When an article is no longer accurate, set its status to Draft to hide it from the portal while you rewrite it, or delete it if it’s genuinely obsolete.

It’s better to have 50 well-maintained articles than 500 stale ones.