Writing a knowledge base article and writing a good knowledge base article are very different things. Most help content is technically accurate but practically unusable — too long, buried under context that customers do not need, written in the passive voice of someone covering their legal bases. Customers read the first sentence, do not find the answer immediately, and open a ticket.
This guide is about writing articles that work: clear, specific, and structured in a way that gets customers to the answer before they give up.
Start With the Right Question
Every article should be built around one specific question or task. Before you write a single sentence, state that question clearly — even if it never appears verbatim in the article.
"How does a customer reset their password if they have two-factor authentication enabled and can no longer access their authenticator app?"
This question is different from "How to reset a password" — it is narrower and more specific. A separate, specific article for this edge case will serve customers better than a single sprawling "Password and Security" article that tries to cover everything.
When in doubt, narrow the scope. You can always link between articles. You cannot easily make a long, unfocused article shorter without rewriting it.
Use Question-Format Titles
Titles written as questions match the way customers search. They also set a clear expectation: the visitor knows exactly what the article will answer before clicking.
Less effective:
- Password Reset
- Billing Overview
- Two-Factor Authentication
More effective:
- How do I reset my password?
- How does billing work?
- How do I enable two-factor authentication?
For questions with a known symptom, the symptom itself makes an excellent title:
- Why am I not receiving the verification email?
- Why is my payment being declined?
- Why can't I see my team members' activity?
These match exactly what a frustrated customer types into a search engine.
Answer the Question in the First Paragraph
The first paragraph of a knowledge base article is not the place for background, history, or caveats. It is the place for the answer — or at minimum, a clear statement of what the article will tell you and the fastest path to it.
Slow start:
Two-factor authentication (2FA) is an important security measure that adds an additional layer of protection to your account beyond just your password. In this article, we will walk you through the process of enabling and using 2FA on your account.
Fast start:
To enable two-factor authentication, go to Settings → Security and click Enable 2FA. Scan the QR code with your authenticator app (Google Authenticator, Authy, or any TOTP app) and enter the 6-digit code to confirm.
The second version answers the question in two sentences. Everything that follows — recovery codes, troubleshooting, disabling 2FA — comes after the primary answer is established.
Write Steps as Numbered Steps
Any process with more than two actions should use a numbered list, not prose. Numbered steps are:
- Easier to follow without losing your place
- Easier to scan to find where you left off
- Less prone to misinterpretation (the sequence is explicit)
Prose version:
To change your email address, you will need to go to your profile settings by clicking on your avatar in the top right corner, then selecting Profile. From there, scroll down to the Email section and click Edit. Enter your new email address and click Save. You will receive a confirmation email to the new address.
Step format:
- Click your avatar in the top right corner and select Profile
- Scroll to the Email section and click Edit
- Enter your new email address
- Click Save
- Check your new email address for a confirmation link and click it
The numbered version is faster to read and harder to misfollow.
Bold UI Elements and Actions
When referring to interface elements — buttons, menu items, field names, page names — bold them. This visual signal helps customers scan quickly to find the specific element they need to click or look for.
Click Save changes to confirm your update.
Navigate to Settings → Team → Invite member.
Do not bold entire sentences or random emphasis. Reserve bold for: button labels, menu items, field names, and keyboard shortcuts.
Use Screenshots Strategically — Not Decoratively
Screenshots are valuable when the interface element being described is hard to find or when the visual context helps. They are not valuable when pasted in automatically to make an article "look complete."
When to use a screenshot:
- The UI element is in a non-obvious location
- Multiple elements look similar and distinguishing them visually helps
- The result of an action (a confirmation message, a changed state) is easier to show than describe
When to skip the screenshot:
- The step is "click Save" — no screenshot needed
- The UI changes frequently and you cannot commit to keeping screenshots updated
When you do use screenshots: mark the relevant element with an arrow, highlight, or numbered callout. A full-page screenshot where the visitor has to find the relevant element themselves is not better than a text description.
Write for Scanning, Not Reading
Customers do not read knowledge base articles — they scan them. They look at headings, bold text, and numbered lists. They stop when they find the relevant section.
Write accordingly:
- Use H2 and H3 headings liberally to break the article into sections
- Keep paragraphs short — three to four sentences maximum
- Use bullet points for lists of items or options
- Do not bury critical information in the middle of a long paragraph
Every section heading should describe what that section covers. "Common issues" is less useful than "What to do if you don't receive the confirmation email".
Anticipate and Address Edge Cases
The best knowledge base articles answer not just the primary question but the follow-up questions that customers have when the standard process does not work.
After the main steps, add a section for:
- "What if [step X] doesn't work?"
- "I completed these steps but [expected outcome] didn't happen"
- "This process looks different on my screen"
These edge cases represent the questions that turn into tickets when the primary article fails to address them. Adding a brief troubleshooting section at the end of your procedural articles can significantly increase their self-resolution rate.
Match the Reading Level to Your Audience
Most customer-facing knowledge base articles should be written at a reading level accessible to a non-technical audience. Avoid:
- Jargon specific to your product or industry that a new customer would not recognize
- Acronyms without explanation on first use
- Overly formal or legalistic language
The test: could a customer who signed up yesterday understand this article without additional context? If not, add the context or simplify the language.
Internal articles — written for agents, not customers — can use more technical language and assume more product knowledge. Keep these clearly separated from public-facing articles.
End With What to Do Next
Every article should close with either:
- A natural next step: "Now that 2FA is enabled, you may want to [download your recovery codes]."
- An escalation path: "If you're still having trouble, [contact our support team] or [start a live chat]."
Do not leave the visitor stranded at the end of the article with no obvious direction. An article that ends abruptly at the last step is a missed opportunity to either deepen engagement with your product or route a stuck customer toward resolution.
How Nura24 Supports Article Quality
Nura24's knowledge base module includes a TipTap rich text editor with support for numbered lists, headings, bold formatting, image uploads, and internal article linking. Article feedback (helpful / not helpful) is collected on the public-facing page, and the AI gap analysis feature flags questions asked in live chat and tickets that no article currently answers — directly pointing to where new content is most needed. Articles can be published publicly or kept internal (visible only to agents), supporting both customer-facing and internal knowledge management in the same workspace.