How to Write a Knowledge Base Article: 7 Steps That Work

A customer searches your help center, finds an article that looks right, and starts following it. Then step four mentions a button that moved two releases ago. Now they’re back in your support queue, more frustrated than before they searched.

People do want to help themselves, especially with simple issues. But that preference says nothing about whether any particular article actually works.

A knowledge base article is a focused, self-service answer that helps a reader solve one problem or complete one task without contacting support. This guide covers how to write a knowledge base article in seven stages, including where AI helps and where a person must step in. You’ll need a real customer question, access to the current product, and any existing documentation on the topic.

TL;DR

• Find one real question in your customers’ own words, and update an existing page before creating a duplicate.
• Choose the article type that fits the reader’s goal, then use one answer-first template.
• Use AI to produce a structured draft, but only from current product documentation you supply.
• Improve the instructions, links, and visuals by hand. Give each action its own step.
• Verify the steps as the intended reader, with the real role and access level.
• Publish with a short workflow: metadata, visibility, preview, approval, and a discovery check.
• Recheck the article whenever the product changes. A new edit date does not prove the steps still work.

Step 1: Find a Question Worth Answering

Every useful article I’ve shipped began with a question someone actually asked. Salesforce’s guidance on knowledge articles starts in the same place: identify common issues and build on content you already have. The University of North Carolina Wilmington’s documented KB process also requires a check for existing content before anyone drafts.

Five Ways I Find Topics

You don’t need all five. Two or three sources that agree are enough to justify an article.

• Google Search Console. Open Performance, then Search results. Filter queries for words like “how,” “why,” and “can’t,” sort by impressions, and look for questions with many impressions and few clicks. Then check whether your documentation actually answers each one. Search Console reflects searches on Google, not searches inside your help center.
• Support tickets. Export the last 30 to 90 days of tickets. Tag each one with the task or problem behind it, then group the tags. Recurring tasks and repeated errors are your strongest candidates.
• Help-center search analytics. Pull the report of zero-result queries. Then find searches followed by an unsuccessful session: no article opened, a quick exit, or a ticket right after.
• Sales, onboarding, and customer-success conversations. Read call notes and onboarding checklists for the same confusion showing up repeatedly. Customers often ask these questions out loud before they ever file a ticket.
• AI analysis of anonymized questions. When the volume is too large to read, let AI cluster it. Strip names, emails, and account details first.

Use This Prompt for the Topic Analysis

Paste the prompt below into your AI tool, then add your anonymized material where the brackets are.

Analyze the anonymized customer questions below and follow the instructions that come first.

1. Group similar items into topics and merge duplicates.
2. For each topic, report the evidence: how many items in the input belong to it, plus two or three short example phrases in the customer's words. Count only what is in the input. Do not estimate or invent frequencies.
3. Suggest one candidate article title per topic, worded the way customers phrase the question.
4. Note which topics appear to have no documentation or outdated documentation, based only on the existing article list at the end.
5. List the unknowns: anything you cannot tell from the input. Do not include names, email addresses, or other personal data in your answer.

Questions, search queries, or notes: [PASTE ANONYMIZED INPUT HERE]

Existing article titles and summaries: [PASTE LIST HERE]

Prioritize With Three Checks

Score each candidate topic on three things.

• Frequency: How often does the question recur across your sources?
• Impact: Does the problem block setup, billing, or security, or is it mild curiosity?
• Coverage: Is there no article, an article that fails readers, or one that already works?

Write first where frequency and impact are high and coverage is missing or failing. If a page exists but is inadequate, update it instead of creating a duplicate.

Check for an Existing Answer Before Writing a New One

• Search for an existing article that already answers the question. If one exists, update it instead of creating a near-duplicate.
• Write down who the answer is for, what they’re trying to do, and what a successful result looks like.
• Note any role, plan, platform, or product-version difference that changes the instructions.

Ten minutes on this checklist saves you from maintaining two half-right articles for years.

Step 2: Choose the Article Type and an Answer-First Structure

Once you know the question, decide what kind of answer the reader needs. Help Scout and Moveworks both describe a handful of article types, and each serves a different reader goal. Choosing the wrong type is a common reason articles feel off even when the facts are correct.

Match the Format to the Reader’s Goal

Every type below is a variation on the same core template, so your library stays consistent. I use the private-help-center scenario in the examples.

Informational overviews and data migration guides are useful too. Add them only when readers have a distinct goal the five types don’t serve.

Keep the Article to One Clear Outcome

Related questions belong in the same article when they share one outcome and one path. “Who can see private articles?” fits inside an article about restricting access. A question with its own steps, like changing your SSO provider, deserves its own article so readers can find and follow it.

When the instructions differ materially by audience or platform, split them under clear headings such as “If you use SAML” or “For workspace admins.” The main path stays at the top. Readers with the common setup should never wade through edge cases to reach their answer.

Copy This Core Template

Use this knowledge base article template as the skeleton for every type. Troubleshooting articles swap the steps for checks and fixes, and FAQs use short question-and-answer blocks.

Title: The task or problem, in the reader’s words.

Short answer: The outcome in one or two sentences.

Applies to: Roles, plans, platforms, or versions covered.

Before you start: Permissions, settings, or information the reader needs first.

Steps: Numbered actions in order, one action each.

How to confirm success: Something the reader can see or test.

If it does not work or related help: A likely fix, a link, or a route to support.

Name the task or problem in the title. “Private help centers” is a topic. “Restrict access to your help center” is a task. “Why can’t an invited reader open a private help article?” is a problem-led title that matches how people search when something breaks. Lead with a verb and the reader’s terminology, and add a plan or platform qualifier only when it changes the answer.

Then make the page easy to scan:

• Put the answer or outcome near the top.
• Use descriptive headings for prerequisites, actions, and exceptions.
• Use numbered lists only for actions that must happen in order, and bullets for everything else.
• Add jump links only when the article is long enough to need them.

Step 3: Use AI to Create a Structured Draft From Your Sources

AI is good at turning scattered material into a clean first draft. It does not know your product, so it will fill gaps with plausible guesses unless you stop it. My rule is simple: AI drafts only from documentation I supply, and it flags what’s missing.

Gather the Source Material First

• The customer question, copied in the customer’s words.
• Current product documentation, release notes, or pull-request descriptions for the feature.
• Verified interface labels, plan requirements, and permissions, checked against the live product.

Paste-Ready Prompts for Each Format

Each prompt carries its own grounding rules, so you can paste any one on its own. Replace the two bracketed slots with your material.

How-to

Write a how-to knowledge base article.

Use only the product documentation below.
Do not invent features, plan requirements, interface labels, or click paths.
Where a fact, step, plan requirement, or label is missing, write [MISSING: what is needed].

Include:
- Title
- Short answer
- Applies to
- Prerequisites
- Numbered steps with one action each
- An observable success check
- A failure or related-help section

Customer question: [PASTE CUSTOMER QUESTION]

Product documentation: [PASTE CURRENT PRODUCT DOCUMENTATION]

Troubleshooting

Write a troubleshooting knowledge base article.

Use only the product documentation below.
Do not invent features, plan requirements, interface labels, or click paths.
Flag anything missing as [MISSING: what is needed].

Include:
- The symptom as the reader sees it
- Applicable prerequisites
- Likely causes ordered by likelihood
- One actionable check and fix for each
- A verifiable success check
- An escalation path

Customer question: [PASTE CUSTOMER QUESTION]

Product documentation: [PASTE CURRENT PRODUCT DOCUMENTATION]

FAQ

Write an FAQ knowledge base article on one bounded topic.

Use only the product documentation below.
Do not invent features, plan requirements, interface labels, or click paths.
Flag anything missing as [MISSING: what is needed].

Include:
- A short topic intro
- Question-and-answer blocks that answer in the first sentence
- Applicable prerequisites or plan limits for each answer
- A verifiable success check where an answer involves an action
- [LINK NEEDED] markers pointing to full how-to articles

Customer questions: [PASTE CUSTOMER QUESTIONS]

Product documentation: [PASTE CURRENT PRODUCT DOCUMENTATION]

Policy

Write a policy knowledge base article.

Use only the product documentation below.
Do not invent rules, plan requirements, or interface labels.
Flag anything missing as [MISSING: what is needed].

Include:
- The rule stated first
- Who it applies to
- Applicable prerequisites or eligibility conditions
- Exceptions
- The effective date or version
- A concrete way for the reader to verify the rule applies to them

Customer question: [PASTE CUSTOMER QUESTION]

Product documentation: [PASTE CURRENT PRODUCT DOCUMENTATION]

Integration guide

Write an integration guide knowledge base article.

Use only the product documentation below.
Do not invent features, plan requirements, interface labels, or click paths.
Flag anything missing as [MISSING: what is needed].

Include:
- Prerequisites and required permissions in both systems
- Numbered connection steps with one action each
- A verifiable check that data flows between the systems
- Common connection errors with fixes

Customer question: [PASTE CUSTOMER QUESTION]

Product documentation: [PASTE CURRENT PRODUCT DOCUMENTATION]

A Worked Example With a Fictional Product

Everything below is illustrative. “Northwind Help” is a fictional product, not Ferndesk, and its labels come only from the made-up source notes shown here. This is not a real product walkthrough.

Spotted the question. In this example, help-center search analytics show a zero-result query, “make help center private,” and recent tickets ask the same thing.

Chose the type. The reader wants to complete one task, so this is a how-to.

Grounded the source input. These are the illustrative notes I paste into the documentation slot:

Northwind Help source notes (fictional):

• Only workspace admins can change access settings.
• Private help center requires the Business plan.
• Path: Settings, then Access.
• Toggle label: “Private help center.”
• Sign-in method dropdown: “Magic link” or “SAML.” SAML setup is covered in a separate article.
• Field for approved readers: “Allowed readers” (email addresses).
• Save button: “Save changes.” Confirmation banner: “Access settings updated.”
• Signed-out visitors see a page titled “Sign in to continue.”

Ran the prompt. I use the how-to prompt, with the customer question “How do I make my help center private?” and the notes above in the two slots. This is the first draft it produces:

Title: Make your help center private

Short answer: Turn on the Private help center setting, choose a sign-in method, and add the readers who should have access. Signed-out visitors will then be asked to sign in before they see any article.

Applies to: Workspace admins on the Business plan.

Before you start:

• Confirm you are a workspace admin.
• Confirm your workspace is on the Business plan.
• Choose Magic link as your sign-in method. For SAML, see the separate SAML setup article.
• Collect the email addresses of the customers who need access.

Steps:

1. Open Settings.
2. Select Access.
3. Turn on Private help center.
4. In the sign-in method dropdown, select Magic link.
5. In Allowed readers, add the customers’ email addresses.
6. Select Save changes.

How to confirm success: The banner “Access settings updated” appears. Then open your help center in a private browser window while signed out. You should see a page titled “Sign in to continue” and no article content.

If it does not work: If you don’t see the Private help center toggle, check your plan and your role. [MISSING: whether existing bookmarked article links redirect signed-out visitors to sign-in.]

Step 4: Improve the Instructions, Links, and Visuals

The draft is a starting point. This is where most knowledge base writing breaks down: the author knows the product too well, skips the “obvious” steps, and the reader gets stuck.

Tighten the Instructions

• Lead with the answer. Say what the reader will accomplish before any background.
• Write to “you.” Use plain names for controls and concepts.
• Give each action its own step. “Turn on restricted access and choose your sign-in method” is two actions. Split it so a reader can stop, check, and resume.
• Flag differences only where they change a step. If SAML needs an extra certificate upload, put the note at that step, not in a general disclaimer.
• Never leave a vague instruction. “Configure authentication” fails a reader who doesn’t know what that involves. Name the prerequisite or link to the article that covers it.

Exceptions get a brief fix, then a link out. A full diagnosis belongs in a troubleshooting article.

Show the Screen Where Words Are Not Enough

Add a screenshot or short video when a control is hard to find or when a visual state confirms success. A toggle buried in a crowded settings page earns a screenshot. A plain “Save” button doesn’t.

Every visual needs an instruction or caption next to it. If the screenshot carries the whole step, readers using screen readers, and readers whose UI looks slightly different, are left guessing.

• Check that each image matches the interface the text describes.
• Write alt text that describes what the reader needs to notice.
• Crop or blur customer data, email addresses, API keys, and credentials.

Link to Prerequisites Without Sending Readers in Circles

• Link once to a heavy prerequisite. If setting up SAML takes ten steps, link to that article instead of repeating it.
• Put optional reading after the core answer. A short “Related articles” section at the end keeps the main path clean.
• Offer a clear route to a person. When the documented steps don’t solve the problem, tell readers how to contact support.

Human Revisions in the Example

Here is what I change in the Northwind draft:

• Resolve the flag. A product owner confirms that bookmarked links redirect to sign-in, so I add that to the success check.
• Add one screenshot. The Private help center toggle sits among other settings, so I add an image with a caption naming it.
• Link the SAML prerequisite once instead of explaining it here.
• Add a related-articles section after the success check, and set the category and tags in Step 6.

Step 5: Verify the Steps as the Intended Reader

I never publish an article I haven’t followed myself. Writing from memory is how missing steps reach customers. Testing takes minutes, and it catches the problems readers would otherwise report as tickets.

Follow the Steps as the Intended Reader

• Start from the stated prerequisites, using the reader’s actual role or access level rather than your admin account.
• Follow every step in order and note missing clicks, unexplained terms, and assumed knowledge.
• Confirm the success check works and the failure guidance points somewhere useful.
• Test each plan or platform difference the article claims to cover.

Testing with a lower-permission account matters more than it sounds. In the private-help-center example, an admin may never see the authentication prompt that a customer sees.

Test Each Role in the Example

Check Accuracy, Style, and Visibility

• Check names, permissions, screenshots, links, and plan or version details against the current product.
• Apply your knowledge base style guide for terminology, formatting, and tone.
• Ask a product or support reviewer to check the steps they know firsthand, and read every sentence of an AI-assisted draft before it goes anywhere.
• Confirm no label, plan requirement, or step came from the model’s imagination rather than your source notes.

UNCW’s documented process builds the existing-content check and the style-guide review into every submission, and that’s the right model to copy. A written review process keeps quality consistent even when different people write each article.

Step 6: Publish With a Short, Concrete Workflow

Reviewed doesn’t mean ready. I run the same short checklist every time I publish a knowledge base article.

• Metadata: Confirm the title, one- or two-sentence summary, category, URL slug, and tags. Use the reader’s search terms and skip keyword stuffing.
• Permissions and visibility: Confirm who can view the article (public, customers only, or internal) and who can edit it.
• Preview: Open the published view and check that the answer, lists, and visuals stay readable.
• Approval: Get sign-off from the reviewer who verified the steps.
• Publish: Schedule the release only when the answer must appear on a release date.
• Discovery check: Search your help center using the customer’s original wording and confirm the article appears. Check the zero-result and search-analytics reports again after a few days.

Step 7: Keep the Answer Accurate After It Goes Live

Publishing is the midpoint, not the finish. The article that was perfect last month can be wrong after one release. I treat maintenance as part of writing the article, because a stale answer does more damage than no answer.

Recheck the Article When the Answer Changes

• Product releases and changed flows: Recheck exact instructions and screenshots whenever the UI or workflow behind an article changes.
• Support signals: Repeated questions, missed searches, and article feedback show where an answer is unclear or missing.
• Small decay: Fix broken links, outdated eligibility details, and changed terminology as part of the article itself.
• Substantive revisions: Retest the reader’s outcome after a significant edit.

A new “last updated” date tells readers someone touched the page. Only a retest proves the steps still work.

Let Drafting Tools Flag Changes, Then Verify the Answer

The hardest part of maintenance is knowing which article needs attention after a release. Many platforms can already draft articles from closed tickets, which helps with new content. Ferndesk adds a maintenance layer: its agent, Fern, can draft documentation changes from customer-facing GitHub pull requests and support context. A person reviews every change before it’s published.

That doesn’t mean every product change arrives with a ready draft, and it doesn’t replace judgment. Ferndesk can also refresh screenshots when the UI changes, which cuts some manual rework. The question I still ask of every update is simple: does this article still guide the reader to the right result?

Conclusion

Knowing how to write a knowledge base article well comes down to seven stages: find a real question, choose the type and answer-first structure, draft from your own sources with AI, sharpen the steps, test as the reader, publish deliberately, and keep it current. If a reader can finish the task without guessing, the article did its job.

• Question: One real customer question, in the reader’s words, with no duplicate article.
• Answer: The right article type, an answer-first structure, and one action per step.
• Verification: Tested as the admin and the intended reader, with an observable success check and a human review of any AI draft.
• Accuracy: Rechecked and retested whenever the product or support signals change.

FAQs: How to Write a Knowledge Base Article

How long should a knowledge base article be?

As long as the task requires and no longer. A single how-to often fits in a few hundred words. If an article keeps growing, it usually covers more than one outcome and should be split.

What is the best format for a knowledge base article?

Answer-first: title, short answer, who it applies to, prerequisites, numbered steps, a success check, and a next step. Troubleshooting articles and FAQs adapt that core shape instead of replacing it.

Should I use screenshots in every article?

No. Use them where a control is hard to find or a visual state confirms success. Every screenshot is something to maintain, so add only the ones that help readers finish.

How do I know which articles to write first?

Score topics on frequency, customer impact, and documentation coverage. Start with recurring support questions, failed help-center searches, and Google queries with many impressions and few clicks.

Can AI write knowledge base articles?

AI can produce a useful first draft when you give it the customer question and current product documentation, and tell it to flag missing facts. It must never publish on its own. A person who knows the product still verifies the steps, tests the outcome, and approves the article.

How often should I update knowledge base articles?

Update them when the answer changes: after releases that affect the workflow, and when support questions or feedback show confusion. A fixed calendar review helps, but product changes are the real trigger.