TL;DR
- Four article types cover most knowledge base needs: how-to (steps), troubleshooting (problem to fix), FAQ (one question one answer), and reference (concept explanation).
- The four examples below are complete, copy-pasteable, and written for a fictional SaaS product so the structure transfers to any tool.
- A copy-paste markdown template for each type sits at the bottom.
The hardest part of writing a knowledge base article is not the writing; it is starting. This guide shows four full sample articles with the structure visible, then gives you the template for each type so you can copy-paste and replace the content with your own product. All examples are written for a fictional analytics SaaS called "Stackflow" so the structure stays portable.
The 4 article types
| Type | When to use it | Example title |
|---|---|---|
| How-to | Step-by-step instructions for a common task | "How to invite team members" |
| Troubleshooting | A specific problem the user is hitting | "Webhooks are not firing" |
| FAQ | A single direct question with one definitive answer | "Can I cancel my subscription mid-month?" |
| Reference / concept | Explanation of a feature, term, or system | "Understanding Stackflow workspaces" |
Most knowledge bases need 60% how-to, 20% troubleshooting, 15% FAQ, 5% reference. Start with the questions your support inbox sees most often, classify each by type, and write in that ratio.
Sample 1: How-to article
How to invite team members to your Stackflow workspace
Add up to 10 team members to your workspace on the Pro plan, or unlimited members on Scale. New members receive a setup email and can sign in within minutes.
Before you start:
- You must be a workspace admin to invite new members. Members and viewers cannot send invites.
- The new member's email must not already belong to another active Stackflow workspace.
Steps:
- Open Settings → Team from the left sidebar.
- Click the Invite member button in the top-right corner.
- Enter the new member's email address. Add multiple members at once by separating emails with a comma.
- Choose a role: Admin, Member, or Viewer. (See Workspace roles explained for the difference.)
- Click Send invites. Each invitee receives an email within 2 minutes.
What happens next:
The invitee clicks the email link, sets their password, and lands directly inside your workspace. Pending invites appear under Settings → Team → Pending. You can resend or revoke them from that screen.
Related articles:
This is a complete how-to. Notice the structure: one-sentence answer at the top, prerequisites before steps, numbered actions with bold UI elements, and "what happens next" so users know success looks like. Total length: 180 words.
Sample 2: Troubleshooting article
Webhooks are not firing in Stackflow
If your configured webhooks are not delivering events to your endpoint, the most common cause is endpoint authentication or signature verification failure. Use the steps below to diagnose, in order.
Step 1: Check the webhook log.
Open Settings → Webhooks → Logs. The log shows the last 100 webhook attempts, their HTTP status codes, and the response body from your endpoint.
- No log entries at all? The trigger event did not fire. Verify in Settings → Webhooks → Active that the webhook is enabled and listening to the correct event type.
- Status 200 in log? The webhook is firing successfully. The issue is on your end after receipt.
- Status 4xx in log? Your endpoint is rejecting the payload. Continue to step 2.
Step 2: Verify signature validation.
Stackflow signs every webhook payload with HMAC-SHA256 using your workspace secret. If your endpoint validates the signature and the secret has rotated, the validation fails.
Check that your endpoint uses the current signing secret from Settings → Webhooks → Secret. If you rotated the secret, redeploy your endpoint with the new value.
Step 3: Check IP allow-listing.
If your endpoint is behind a firewall with IP allow-listing, ensure Stackflow's webhook IPs are allowed. The full list is at docs.stackflow.com/webhooks/ips and updates monthly.
Still not working?
Open Settings → Webhooks → Logs, click the failed event, and copy the request ID. Send it to support@stackflow.com and we will trace it within 1 business hour.
Notice the structure: state the problem in the title, give the most-common cause up front, then steps in diagnostic order. Each step has a clear "if this, then that" branch. Total length: 250 words.
Sample 3: FAQ article
Can I cancel my Stackflow subscription mid-month?
Yes. You can cancel from your billing dashboard at any time. Your subscription stays active until the end of the current billing period; you are not charged for the next period.
Where to cancel:
Go to Settings → Billing → Manage subscription and click Cancel subscription. You will see your end date confirmed before you finalize.
What happens to your data:
Workspaces remain accessible read-only for 30 days after your end date. After 30 days, data is permanently deleted unless you reactivate. To export beforehand, use Settings → Workspace → Export.
Refund policy:
Stackflow does not pro-rate refunds for partial months. The end date of your last paid period is your final access date. For exceptional circumstances, contact billing@stackflow.com.
FAQ articles are short by design. One question, one direct answer, one paragraph each on the most-common follow-up questions. Total length: 130 words.
Sample 4: Reference / concept article
Understanding Stackflow workspaces
A Stackflow workspace is the top-level container for your team's projects, members, and billing. Each workspace has its own subdomain, billing plan, member roster, and feature access. You can belong to multiple workspaces with one Stackflow account.
When to use multiple workspaces:
- Separate environments. Most teams use one production workspace and one staging workspace so developers can test without affecting live data.
- Multiple companies. Consultancies and agencies create one workspace per client so data and billing stay isolated.
- Mergers and acquisitions. Pre-merger, each company keeps its workspace. Post-merger, you can migrate or maintain both.
What lives at workspace level:
- Members and roles
- Billing plan and payment method
- Custom domain and branding
- Integrations and API keys
- Feature access (Pro vs Scale features)
What lives below workspace level:
- Projects (containers for your data)
- Dashboards and reports
- Member-specific preferences
Switching between workspaces:
Click your workspace name in the top-left corner of any page. A dropdown shows all workspaces you belong to. Click any workspace to switch context immediately; data does not transfer between workspaces.
Reference articles explain concepts that other articles assume. Total length: 250 words.
Copy-paste templates
How-to template
# How to [action]
[One-sentence summary of what this article achieves]
**Before you start:**
- [Prerequisite 1]
- [Prerequisite 2]
**Steps:**
1. [Action with bold UI element]
2. [Action with bold UI element]
3. [Action with bold UI element]
**What happens next:**
[What success looks like, where to verify]
**Related articles:**
- [Link 1]
- [Link 2]
Troubleshooting template
# [Problem in plain language]
[One-sentence statement of the most common cause]
**Step 1: [Diagnostic action]**
[Description with branch logic: "if X, then Y"]
**Step 2: [Next diagnostic]**
[Description]
**Step 3: [Next diagnostic]**
[Description]
**Still not working?**
[Escalation path with the data the support team needs]
FAQ template
# [Single direct question]
[One-paragraph direct answer]
**[Sub-question 1]:**
[1-2 sentence answer]
**[Sub-question 2]:**
[1-2 sentence answer]
Reference template
# Understanding [concept]
[One-paragraph definition with the why]
**When to use it:**
- [Scenario 1]
- [Scenario 2]
**What's included:**
- [Component 1]
- [Component 2]
**Related concepts:**
- [Link to related concept]
Checklist: kenmerken of a good knowledge base article
- Title matches a real customer search query (not internal jargon)
- First sentence is the answer, not the setup
- One topic per article (split if you find yourself using "and" in the title)
- Step-by-step where possible, with bold UI element names
- One screenshot per non-obvious step
- Related-article links at the bottom
- Article ownership assigned (someone reviews quarterly)
Frequently asked questions
How long should a knowledge base article be?
Most should be 200 to 400 words. Customers skim. The longest articles in this guide are 250 words. If your article is over 600 words, it probably should be two or three separate articles.
Should I use video in knowledge base articles?
Use video only when steps are non-obvious without it. Video is harder to scan than text, harder to search inside, and harder to update. A 30-second clip embedded in a how-to article works; a 10-minute walkthrough does not.
How many articles do I need to start?
Start with 5 articles covering your top 5 most-asked questions. Reach 15 to 20 articles before AI search becomes meaningfully useful (it needs corpus depth). Most teams hit 30 to 60 articles within 6 months.
Should I write articles myself or use AI?
Use AI to draft from your existing support replies, then have a human edit for accuracy and tone. AI Writer Plus in Helpable, Document360 AI, and Helpjuice Swifty all do this well. Pure AI generation without a human pass produces hallucinations and bland prose.
How often should I update articles?
Quarterly review of the top 10 most-viewed articles. Annual review of everything else. Archive articles with under 10 views in 90 days. The dashboard in most modern KB tools (Helpable, Document360, Zendesk) surfaces stale articles automatically.
Stop writing these manually
Writing 15 articles from scratch takes 10 to 15 hours. AI Writer Plus inside Helpable drafts each article from your existing support reply: paste the question and your saved answer, and the AI returns a structured article with intro, steps, and screenshot placeholders. Most teams cut writing time per article from 60 to 90 minutes down to 20 to 25.
Start a free 7-day Helpable trial and try AI Writer Plus on Pro. EU-hosted, $49 per month flat for Starter. See the knowledge base feature page for more.
Related articles
- How to Write Knowledge Base Articles
- How to Build a Knowledge Base
- How to Organize a Knowledge Base
- What Is a Knowledge Base?
- Best Knowledge Base Software for SaaS
Last updated: May 2026