How to Write Knowledge Base Articles: 6 Templates and a Review Workflow

Useful knowledge base articles answer one recognizable question or help someone complete one task. Choose a format that matches the reader’s situation, include the context needed to use the answer, and make the expected result clear. “I need to invite a colleague” calls for a how-to guide. “I cannot see the invite option” may require troubleshooting because the cause could depend on role, plan, or interface.

This guide provides six adaptable editorial formats and a practical review workflow. These are editorial patterns, not official HubSpot or KCS templates. Use them to shape content around real support questions, then verify product instructions with the people and documentation responsible for them.

The guide also shows how to capture support context with KCS concepts and how to use AI for a bounded first draft without presenting a proposed workflow as a native HubSpot integration.

What makes a knowledge base article useful?

A knowledge base article is practical reference content organized to help a reader complete a task or resolve a question. A blog post may explore a broad topic or point of view. A knowledge base article should get the reader to a usable answer with as little detour as the task allows.

Before drafting, write the reader’s need as one sentence: “I want to…” for a task, or “I see…” for a problem. If the draft cannot answer that sentence directly, narrow its scope. Put the answer or goal near the top, state who the guidance applies to, and show what success looks like.

A useful minimum usually includes a search-aligned title, a concise purpose, relevant audience or prerequisites, the answer or procedure, an observable result, and a next step if the guidance fails. Do not force every article into the same length or section count. Use the shortest structure that preserves the context needed to complete or diagnose the task.

Choose the article format from the user’s situation

Start with what the reader needs to do or understand, not the format your team prefers. A support case may also need KCS-style issue and environment details, even when the final article is a how-to or troubleshooting guide.

User situation	Best-fit format	Required structure
Knows the goal	How-to	Prerequisites, ordered actions, expected result
Unexpected symptom	Troubleshooting	Symptom, environment, likely causes, fixes, escalation
Short, repeated question	FAQ	Question, direct answer, qualification or link
Has not configured the product	Getting started	Audience, setup, first useful action, next step
Unsure about a capability or limit	Feature explainer	Purpose, eligibility, use, limitations
A change needs explaining	Release notes	Change, impact, effective date, required action

For example, a missing invite option is not simply a task guide. The cause may depend on a person’s role, plan, or product interface. A troubleshooting brief should capture those details before anyone writes a fix.

Build every article around a clear reader contract

A reader should be able to tell whether the guidance applies, follow the answer or procedure, recognize the result, and know what to do if it does not work. For troubleshooting, identify the relevant product or feature, account plan or role when applicable, platform or version, exact error or symptom, and any material recent change.

For procedures, order actions and describe what the reader should see after important steps, rather than ending at the last click. For a feature explainer, separate what the feature does from who can access it. For release notes, make the required action prominent and state when it takes effect.

Adapt six practical knowledge base article templates

Use these fill-in structures as starting points, not fixed forms. Add sections only when they help the reader act or decide.

1. How-to article

Structure: How to [complete task] → goal → prerequisites and permissions → numbered actions → expected result → recovery or related content.

State what the reader will accomplish and who can perform the task. Put permissions and account requirements before the steps. After important actions, describe the visible result. End with a recovery path if the result does not appear.

Greenhouse’s job-creation guide illustrates product-specific procedural guidance, including permissions, setup choices, and approval considerations. It is an example of a complete how-to article, not a universal writing template.

2. Troubleshooting article

Structure: [Symptom in the user’s words] → applicability and environment → likely causes → fixes ordered by likelihood and risk → expected result → escalation path.

Make the environment useful rather than decorative. Capture the product or feature, role or plan, interface or platform, version where relevant, exact error text, and recent configuration changes. Order fixes so that low-risk, common checks come before disruptive changes.

For a missing invite option, check role and plan eligibility before suggesting interface steps. If the environment is unknown, ask for it or route the question to support rather than presenting a guess as a fix.

3. FAQ article

Structure: [Question] → direct answer first → brief qualification → link to a fuller procedure if needed.

Use an FAQ when the answer is short and stable. If the answer depends on several diagnostic conditions, link to a troubleshooting article instead of compressing the decision path into a vague sentence. Keep the answer easy to scan and make the boundary of the answer clear.

4. Getting-started article

Structure: who it is for → prerequisites → setup → first meaningful action → next step.

Explain what is being configured and why the first action matters. Do not make onboarding a tour of every feature. Give the reader one successful first outcome, then point to the next logical task.

Slack’s quick-start guide is an example of onboarding material covering navigation, channels, search, workflows, apps, and related actions. It is product guidance, not proof of a standardized external template.

5. Feature explainer

Structure: purpose → eligible roles or plans → how to use it → limitations and edge cases → related features.

Lead with the decision the reader is trying to make. Explain what the feature does, who can use it, and what it does not do. If eligibility changes by plan or permission, identify the current source for that information and assign an owner to review it when the product changes.

6. Release notes

Structure: what changed → effective date → user impact → action required and deadline, if any → help link.

Make the required action prominent. If no action is required, say so. A description of the change should not force users to infer whether they need to do anything.

Use KCS structure when an article comes from a support case

Knowledge-Centered Service, or KCS, is a broader practice for capturing, reusing, and improving knowledge while solving requests. It is not merely a four-field template. The KCS simple structure commonly includes a title, issue, environment, resolution, metadata, and an optional cause. Environment records context such as the relevant product, version, configuration, process, or recent change.

See the Consortium for Service Innovation’s guidance on the KCS simple template. The reader-facing format still depends on the user’s need. KCS fields preserve context and provenance; they do not dictate whether the published article should read as a how-to, FAQ, or troubleshooting guide.

1. Search existing knowledge first. If an article already addresses the issue, improve it rather than making a duplicate for wording alone. KCS describes this search-and-improve practice in its guidance on improving knowledge while solving a request.
2. Capture the issue in recognizable language. Preserve the user’s terms, then add enough environment detail to distinguish the problem from similar issues.
3. Add only a verified resolution. Include a cause when it is known and useful. Do not infer a cause simply to complete a field.
4. Preserve provenance. Link the article to its source case where the system permits. KCS guidance supports linking knowledge with cases or other systems of record.

Turn article requests into a controlled workflow

The six formats are editorial decisions. A production knowledge process also needs an input, an owner, a validation gate, a destination, and a fallback when the source is incomplete. The following patterns are practical designs, not claimed vendor modules.

Trigger	Drafting or editorial job	Validation gate	Destination and fallback
Known task or content request	Select how-to, getting started, or feature explainer and define the reader contract.	Owner confirms audience, permissions, scope, and existing related content.	Editorial draft; narrow the scope when the request contains multiple tasks.
Unexpected support symptom	Choose troubleshooting and capture issue, environment, causes, fixes, and result.	Verify the symptom, environment, and resolution; do not fill unknown fields by inference.	Support-reviewed article; request missing product or role details.
Resolved support case	Search first, then adapt KCS fields into the reader-facing format.	Confirm the case is resolved and the resolution is reproducible.	Update an existing article or create a linked draft; escalate uncertain fixes.
Product or policy change	Write release notes with impact, effective date, and required action.	Change owner confirms the date, audience, behavior, and deadline.	Publish or schedule through the authorized editor; state when no action is needed.

Use AI for a bounded draft, not article approval

AI can help rewrite a reported issue into searchable language, suggest an article type, propose tags, identify missing context, or draft from verified source material. It should not invent a cause, resolution, product behavior, permission rule, or environment detail.

The workflow below is a proposed design informed by structured KCS fields and documented workflow capabilities. HubSpot documents workflow creation and publication, but the cited workflow documentation does not establish a native knowledge-base article-generation pipeline, an article approval gate, or race-safe deduplication.

A structured draft queue can make missing information visible:

{
  "title": "Why the invite option may not be visible",
  "article_type": "troubleshooting",
  "issue": "The user cannot find the option to invite a colleague.",
  "environment": {
    "role": null,
    "plan": null,
    "interface": "unknown"
  },
  "resolution": null,
  "source_case_id": "case-illustrative-1042",
  "reviewer_status": "awaiting_subject_matter_review"
}

The null values are a deliberate stop signal. The draft should not be published until an owner verifies the role, plan, interface, and resolution.

For a local queue that may receive concurrent writes, use a database-enforced unique constraint or transactional upsert. A lookup followed by an insert is not sufficient because two concurrent runs can both fail to see an existing row. An illustrative draft key could be source_case_id plus prompt_version, model_version, and draft_revision. This is a proposed local design, not a confirmed HubSpot schema or API behavior.

For teams assessing a broader implementation, see AI agent services. This optional resource does not imply that HubSpot supplies the workflow described here.

Publish, organize, and review articles with clear ownership

Assign a content owner who can decide whether an article needs correction, review, or retirement. Trigger a review after a product or interface change, a policy update, repeated support contacts, negative article feedback, failed searches, or a change in the source process. Use views, feedback, search behavior, and related support demand to prioritize maintenance. Do not assume that an exact percentage of articles accounts for most of the value.

Before publishing, confirm that the title matches user language, the goal or symptom is explicit, the steps are testable, the expected result is observable, links and media are current, the audience and category are correct, and an existing article was checked. Record the reviewer and source so a future editor can verify why the guidance exists.

HubSpot’s current documentation describes article titles, subtitles, body content, media, links, categories, tags, visibility, preview, feedback, and publishing or scheduling controls. Article creation and some settings depend on the relevant Service Hub subscription, seats, permissions, account configuration, and whether the knowledge base is migrated or legacy. Check the official article-editor instructions for the target account.

HubSpot also documents categories, subcategories, and tags. Organize them around how readers look for answers rather than a universal category-count rule. For multilingual content, check the current documentation for language and category translation requirements.

For an authorized editor, the practical sequence is to confirm access and audience, assign the required category and language, check links and visibility, preview supported device views, then publish or schedule using the controls available to that account. If you need help configuring HubSpot systems, see HubSpot systems consulting.

Keep measurements at their actual grain. An individual “Was this article helpful?” response is an observation. A daily article report is an aggregate. If reporting daily views or feedback, define one summary row by article_id, date, and aggregation period, and do not treat that row as an individual reader event.

Frequently asked questions

How long should a knowledge base article be?

Long enough to complete or diagnose the task, but no longer than the necessary context requires. A fixed word count is less useful than clear applicability, usable instructions, and an observable result.

How often should articles be reviewed?

Review when product behavior, policy, or user feedback gives you a reason to suspect that the article is stale. Use search failures, article feedback, views, and related support demand to prioritize ongoing maintenance. Assign an owner to act on those signals.

Can I import articles into HubSpot?

HubSpot documents imports from Freshdesk, Help Scout, Zendesk, Intercom, and CSV. Its documented CSV import requires URL, title, category, and body; the documentation states a limit of 400 articles per import and says tables are not supported. See the current import instructions and confirm account configuration before planning a migration. Inventory content and owners, map required fields, test a small import, and review the result.

Does HubSpot provide these six article templates?

No. They are editorial patterns in this guide. HubSpot’s documented article editor is a product procedure for creating and publishing content, while KCS is a wider knowledge practice with its own structure and workflow.

How do I prevent duplicate articles?

Search before drafting, compare the issue, environment, cause, and resolution with existing content, and repeat the duplicate check immediately before publication. If concurrent automation is possible, use a database-enforced unique constraint or transactional upsert for the relevant row grain. Do not rely on a lookup followed by an insert.