KB Articles, Runbooks & Tickets: Three Different Documents for Three Different Purposes

Documentation & Runbooks

Chapter 2 · KB Articles, Runbooks & Tickets: Three Different Documents for Three Different Purposes

A support technician produces three genuinely different kinds of documents, and conflating them is one of the most common, most quietly damaging mistakes in this whole subject. Each answers a different question, for a different reader, at a different point in time — knowing which one you're actually writing before you start is the first real skill this course teaches.

Three Documents, Three Questions

KB Article

Answers: "What is this, and why does it behave this way?"

Explanatory, conceptual, durable — background and context, not necessarily a walkthrough.

Runbook

Answers: "What do I do, step by step, to accomplish this?"

Procedural, durable, reusable — a precise sequence of actions. Chapter 4 covers its own proper shape.

Ticket

Answers: "What happened this specific time?"

A one-off historical record for a single incident — `incident1`'s own territory, not a reusable procedure.

Why Conflating Them Actually Hurts

A runbook padded with background explanation becomes hard to follow step by step under real pressure — the "why" belongs in a linked KB article, not woven into the steps themselves
A ticket written as if it were a reusable procedure wastes effort generalizing something that may never recur in exactly that form — and if it does recur, it belongs promoted into a real runbook, not left buried in ticket history where nobody will find it again
A KB article with no procedural content, when the reader actually needed concrete steps, leaves them with theory and no clear action to take

When One Should Become Another

A single ticket documenting one incident is exactly the right document the first time something happens. Once the same problem recurs — the specific pattern `incident1`'s own material teaches recognizing — that recurring pattern deserves promotion into a genuine runbook, not another one-off ticket that repeats the same investigation from scratch. Likewise, if a runbook's own background section keeps growing, that's a sign it should be split out into its own linked KB article, leaving the runbook itself lean and purely procedural.

Comparing the Three Directly

	KB Article	Runbook	Ticket
Purpose	Explain	Guide action	Record history
Scope	General, durable	General, durable	One specific instance
Reusable?	Yes	Yes	No — but may reveal a pattern worth promoting
Shape	Prose, diagrams, context	Numbered steps, expected outputs	Timeline, what was done, resolution

Worked Example: From Ticket to Runbook to KB Article

A specific service crashes under load for the first time — a ticket records what happened and how it was resolved. It happens again, and a third time — the recurring pattern is now promoted into a genuine runbook: the exact steps to mitigate and restart the service safely. Separately, a linked KB article explains why the service crashes under load in the first place — the underlying architectural cause, useful context for understanding the problem, but not itself a set of actionable steps. Three documents, three purposes, each doing its own job.

Don't make one document try to do all three jobs

Cramming explanation, procedure, and incident-specific detail into a single document usually means it serves none of the three purposes well — a reader looking for quick steps has to wade through background, and a reader looking for context has to wade through procedural minutiae that doesn't apply to their situation.

Hands-On Exercises

Exercise 1

Using the worked example, explain why the crashing service eventually needed all three document types, rather than one thorough document covering everything.

📄 View solution

Exercise 2

Explain why a runbook padded with background explanation is described as harder to follow under pressure, even though the added information is accurate and relevant.

📄 View solution

Exercise 3

Explain what specifically should trigger promoting a ticket-documented issue into a real runbook, and why writing a runbook after the very first occurrence would usually be premature.

📄 View solution

Chapter 2 Quick Reference

KB article: what is this and why — explanatory, durable, not necessarily procedural
Runbook: step-by-step actions to accomplish a specific task — durable, reusable, procedural
Ticket: what happened this specific time — one-off, historical, not reusable on its own
A recurring pattern in tickets deserves promotion into a runbook; a growing background section deserves its own linked KB article
Don't make one document try to serve all three purposes at once
Next: Chapter 3, writing for the reader at 3am — clarity under pressure