How to Write Knowledge Base Articles People Actually Use
A practical guide to writing internal knowledge base articles — titles in the reader's words, the answer first, numbered steps, screenshots used sparingly, a fixed template, and ownership so articles stay true.
To write knowledge base articles people actually use, title each one with the question as readers ask it, put the answer in the first two lines, follow with numbered steps that name every button exactly, add what to do if it doesn't work, and keep one topic per article. Use a fixed template, give each article an owner and a review date, and write the next one from the questions people asked this month.
Why most internal articles go unread
Internal knowledge bases fail in predictable ways:
- Written from the team's point of view. "SSO architecture overview" when people search "can't log in".
- The answer is buried. Three paragraphs of background before step one.
- Out of date. One wrong screenshot and readers stop trusting the whole knowledge base.
- Nobody knows they exist. They live in a portal people never open.
Each is fixable with habits, not software.
Start from real questions
Don't write the knowledge base you think people need. Export the last three months of requests, group them by what was asked, and write for the biggest groups first. Ten articles covering the ten most repeated questions will deflect more requests than a hundred written from a table of contents. How to put them in front of people at the moment they ask is covered in ticket deflection with a self-service knowledge base.
The title: the reader's question
Titles do most of the work — for search, for skimming and for AI retrieval.
| Team-centric title | Reader-centric title |
|---|---|
| VPN client configuration | Connect to the VPN from home |
| MFA enrolment procedure | Set up two-step sign-in on a new phone |
| Expense policy v3 | Get reimbursed for a work expense |
| Printer fleet | Fix "printer offline" on floor 3 |
Use the words people use, including informal ones ("wifi", not "wireless LAN"). If people ask it two ways, put the second in the first line or in a list of alternate phrasings. LetRelay's own in-app guide lists real phrasings with each page — "make someone admin", "change someone's role" — which also helps search and the assistant find it.
The answer first
Readers scan the top and leave. Put the complete short answer in the first two lines:
To connect from home, open the GlobalConnect app and sign in with your work email. You'll be asked to approve on your phone.
Then the details for anyone who needs them. The UK Government Digital Service's guidance on writing for the web makes the same point: people read the first words of lines and paragraphs, so front-load the meaning.
Steps: numbered, exact, one action each
An example from LetRelay's own guide, for giving someone admin access:
- Open Settings → Users.
- Find the person's row.
- In their Position dropdown, pick a position with Admin access. It saves as soon as you pick — there's no Save button.
(Only the organization's owner can do this; the article says so up front.)
Rules:
- One action per step. "Open Settings and change the position" is two steps.
- Exact labels in bold, matching the screen word for word, including capitalization. If the button says "Save changes", don't write "Save".
- Start each step with a verb.
- Say what happens when it's not obvious: "A confirmation email arrives within a minute."
Screenshots: sparingly
Screenshots help for visual tasks and go stale fastest. Use them when the screen is genuinely confusing, crop to the relevant area, and never let a screenshot carry information missing from the text — screen readers and search can't read it. When the interface changes, text is easier to update than images.
"If it doesn't work"
Every how-to needs an exit:
- The two or three most common failure causes and their fixes.
- What to include if they file a request: "Include the error message and the time it happened."
- A direct link to file a request in the right category.
Self-service that fails should end in a good request, not a dead end.
A template
Use the same structure for every article so readers know where to look:
# [Question in the reader's words]
[One or two sentences: the complete short answer.]
## Steps
1. …
## If it doesn't work
- …
- Still stuck? File a request: [link]
---
Owner: [name / team] · Last reviewed: [date] · Applies to: [who]Keep it true: owners and review dates
An outdated article does more harm than a missing one: it sends people confidently down the wrong path. Every article gets:
- An owner — a person or team responsible for its accuracy.
- A review date — quarterly for fast-changing tools, yearly for stable policies.
- A change trigger — when a tool's interface changes, the owner updates the articles about it before announcing the change.
Show "Last reviewed" on the article. Readers trust dates.
Before and after: one article rewritten
A real-world style "before":
Remote Access Solution — Overview Our organization utilizes a remote access solution to provide secure connectivity to internal resources. The solution was deployed in 2023 following an evaluation of several vendors. In order to utilize the solution, users should ensure that the appropriate client software has been installed on their device (see Software Catalogue) and that they have been provisioned with the necessary entitlements…
The same content, rewritten:
Connect to the VPN from home Open the GlobalConnect app, sign in with your work email, and approve the prompt on your phone. That's it.
Steps
- Open GlobalConnect (install it from Company Portal if it's missing).
- Enter your work email and select Sign in.
- Approve the sign-in on your phone.
If it doesn't work
- "Not entitled": you don't have VPN access yet — file an Access request.
- Keeps disconnecting: switch from Wi-Fi to a cable if you can, then file a request with the time it dropped.
The second version is shorter, answers in the first line, names buttons exactly and tells the reader what to do next when it fails. The background — vendors, deployment history — belongs in an internal design document, not in the help article.
Tone and language
- Second person, active voice. "Open Settings", not "Settings should be opened".
- Plain words. "Use", not "utilize"; "set up", not "provision".
- No blame. "If you see 'Not entitled'…", not "If you forgot to request access…".
- Consistent terms. Pick one word for each thing — "request" or "ticket", not both — and use it everywhere, including in your categories and forms.
Make them findable
- Search that understands meaning. "Can't get on wifi" should find "Connect to the office wireless network". See semantic search with Supabase pgvector.
- Suggestions in the request form, while people type.
- Links from agents. When an agent answers a request that an article covers, link the article. People learn the knowledge base exists.
- An assistant grounded in the articles — it answers from them and says so when they don't cover the question. See RAG for internal documentation.
Write from resolved requests
The best source of new articles is yesterday's queue. When an agent writes a good answer to a common question, turn it into an article draft: the request's wording becomes the title, the agent's reply becomes the steps, and the owner edits it for a general audience. An AI model can draft this from the thread; a person reviews and publishes.
Measure what matters
- Views during request creation followed by "this solved my problem" — the clearest sign an article works.
- Searches with no good result — your writing backlog.
- Articles past their review date — your maintenance backlog.
FAQ
How long should a knowledge base article be?
As short as the task allows: a one-line answer, the steps, and troubleshooting. Split anything covering several tasks into separate articles.
What makes a good knowledge base article title?
The question in the reader's own words — "Connect to the VPN from home" rather than "VPN client configuration" — so it matches how people search.
How often should knowledge base articles be reviewed?
Quarterly for fast-changing tools and yearly for stable policies, plus whenever the underlying tool or process changes.
Should knowledge base articles include screenshots?
Only when the screen is genuinely confusing. Screenshots go stale quickly and can't be read by search or screen readers, so the text must stand alone.
Sources
Building Relay — the internal request desk with AI triage and SLA tracking.
Run your internal requests on LetRelay
AI triage, SLA-tracked queues, and bottleneck analytics — the help desk your team actually likes. Free to start.
Keep reading
HR Service Desk: Handling Employee Requests Without the Inbox
How an HR service desk works — categories for pay, leave, contracts and benefits, privacy that's enforced not promised, targets that respect deadlines like payroll, self-service for policy questions, and the metrics HR can use.
How to Reduce Password Reset Tickets (Securely)
Password resets are one of the most repetitive help desk requests. Cut them with self-service reset, fewer passwords (single sign-on), modern password rules from NIST, and a secure verified process for the resets that still reach a human.
RAG for Internal Documentation: A Small-Team Guide
How to build retrieval-augmented generation over your internal docs without a big platform — structuring documents for retrieval, hybrid search, small prompts, grounding rules, permissions, and measuring whether answers are right.