Writing effective articles

An article is effective when three readers succeed with it: a stressed user searching at 6 pm, an agent mid-ticket, and the AI building an answer from it. The same habits serve all three.

Create an article

1. Open Knowledge base → Create an article.
2. Title, summary, content; pick a category; add tags, and link the service or configuration item it concerns.
3. Choose the visibility — Internal for team procedures, Public for anything a customer may read.
4. Save as draft, review, publish.

Titles: name the problem, not the solution

People search with their problem’s words. Prefer “Can’t connect to the VPN” over “VPN client reinstallation procedure” — the second is what you did, the first is what they typed.

Structure for scanning

• Summary first: one or two sentences saying when this article applies.
• Numbered steps for procedures, one action per step, in the imperative: Open…, Click…, Restart….
• State the expected result after key steps — it is how readers know they are still on track, and how the AI knows what “fixed” looks like.
• One problem per article. Two problems in one article means neither is found.

Write for the AI too

The AI answers with what the article says, so:

• Spell out conditions: “If the light is red, the link is down” beats “check the light”.
• Avoid “as usual” and “the standard way” — the AI (and the new hire) does not know your usuals.
• Keep public articles free of internal contact details or tool names you would not want quoted to a customer — the AI only uses public articles with outsiders, but a public article’s whole content is fair game.

Metadata is retrieval

Tags, category and service are not decoration: the suggestion panel matches on them, so an article tagged vpn with the service Remote access surfaces beside a ticket that says only “can’t work from home”. Sixty seconds of tagging beats a paragraph of keywords.

Keep it alive

• Review articles whose votes turn negative — they are answering wrong or aging.
• Archive what no longer applies instead of deleting; history keeps its value.
• After resolving a ticket the base could not answer, spend five minutes writing the article — next time, the base answers.