Writing KB Articles People Actually Use

The knowledge base article existed. Nobody could use it.

The steps were there. The solution was correct. The person who wrote it clearly knew how to resolve the issue. But the article was written for someone who already knew the answer, not for someone who was looking for it.

No context for why each step mattered. No guidance for when the expected screen did not appear. No note about which environments the fix applied to and which it did not. Just a numbered list that assumed the reader shared the author's mental model of the system.

In a high-volume IT support environment, a knowledge base article that only works for the person who wrote it is not documentation. It is a private note stored in a shared location.

Why Do KB Articles Fail?

The most common reason a knowledge base article fails to help the person who finds it is that it was written from the solution backward, not from the problem forward.

The author knows what the fix is. They document the fix. They do not document how they arrived at the fix, what the problem looked like before the fix was applied, or how to recognize that this particular fix is the right one for this particular situation.

A support agent searching for help is starting from a symptom: what the user told them, what the error message says, what the system is doing. They are not starting from the solution. If the article does not connect the symptom to the fix, it is invisible to the person who needs it most.

Three Things That Make an Article Actually Work

1. State the symptom first, not the fix.

The title and the first paragraph of any KB article should describe the problem in the same terms the user or agent would use to describe it. "User cannot log in after password reset" will be found in a search. "Credential Manager cache clearance procedure" will not, unless the agent already knows what Credential Manager is and why it matters.

Write the title as the problem. Write the first sentence as the symptom. Write the second sentence as what the article covers.

2. Flag the decision points.

Real support scenarios do not always match the documented scenario exactly. A step that looks different depending on whether the user is on a domain-joined machine or a personal device needs to say so. A fix that applies to Windows but not macOS needs to say that. A step that requires elevated permissions the agent may not have needs to identify the escalation path.

Decision points are where articles break down in practice. The agent reaches step three, the expected screen does not appear, and there is no guidance for what to do next. The article becomes useless at exactly the moment it was most needed.

3. Write it for someone on their first week.

This is the most reliable test for whether an article is ready to publish. If a new agent, with no prior experience on this system and no access to the person who wrote the article, could follow it successfully, the article is ready. If they would need to call someone for clarification, it is not.

This standard is not about writing for the lowest common denominator. It is about removing the implicit knowledge that the author carries but has not documented. That implicit knowledge is exactly what the next person does not have.

What Does Good Documentation Look Like?

A well-written KB article for a standard IT support scenario should include:

• Symptom description: What the user reports or what the agent observes that leads to this article
• Scope: Which systems, environments, or user types this fix applies to (and which it does not)
• Prerequisites: Any access level, tool, or information the agent needs before starting
• Steps: Numbered, in order, with expected outcomes noted for steps where the result confirms the next step is appropriate
• Decision points: Explicit branches for common variations ("If the screen shows X instead of Y, proceed to step 7")
• Escalation path: What to do if the fix does not resolve the issue or if the agent lacks the access required
• Verification: How to confirm the fix held before closing the ticket

This sounds like a lot. In practice, for a standard account unlock or password reset procedure, it is three paragraphs and a numbered list. The structure ensures nothing critical is missing.

The Repeat Contact Test

The best proxy measure for whether your knowledge base is working is your repeat contact rate. When the same users are calling back about the same issues, the most common root causes are either that the fix did not hold (a documentation problem in the ticket) or that the agent did not have the information needed to apply the full fix (a KB article problem).

A knowledge base that reduces repeat contacts is not just efficient. It is the difference between a support team that is constantly putting out the same fires and one that is actually making progress on the problems it was built to solve.