Article Templates

Ready-to-use templates for the four core knowledge base article types. Copy the structure, adapt the content to your product, and follow the checklist before publishing.

How-to article template

Use for: step-by-step task completion ("How do I do X?")

# [Action verb] [object] [optional context]

Examples:
  "Add a team member to your workspace"
  "Connect your Slack workspace"
  "Export project data as CSV"

[One sentence stating what the article helps the user accomplish.]

## Before you start

- [Prerequisite 1 - e.g., "You must be a workspace Admin"]
- [Prerequisite 2 - e.g., "The team member needs a valid email address"]

(Omit this section if there are no prerequisites.)

## Steps

1. Go to **Settings** > **Team Members**.
2. Click **Invite Member**.
3. Enter the team member's email address in the **Email** field.
4. Choose a role from the **Role** dropdown:
   - **Admin** - Full access to settings and billing
   - **Member** - Standard access to projects
   - **Viewer** - Read-only access
5. Click **Send Invitation**.

## What happens next

[Describe the outcome the user should see. Set expectations: confirmation
messages, emails, timing, or follow-up actions required.]

Example: "The team member receives an email invitation. They have 7 days
to accept before the link expires. Track pending invitations in
**Settings** > **Team Members** > **Pending** tab."

## Related articles

- [Manage team member roles and permissions](#)
- [Remove a team member from your workspace](#)
- [Understand workspace permission levels](#)

How-to writing checklist

• Title starts with an action verb (Add, Create, Set up, Connect, Export, Reset)
• Opening sentence states the outcome, not the background
• Prerequisites listed before the steps (or section omitted if none)
• One action per numbered step - no compound steps ("Click X and then Y")
• UI element names bolded exactly as they appear in the product
• Sub-options formatted as indented bullet list inside the relevant step
• "What happens next" section sets expectations after the last step
• 2-3 related articles linked at the bottom
• Word count: 150-400 words

Troubleshooting article template

Use for: diagnosing and resolving a specific error or broken behavior ("X is not working")

# [Problem statement in the user's own words]

Examples:
  "I can't log in to my account"
  "My CSV export is empty"
  "Team members aren't receiving invitation emails"

[One sentence acknowledging the problem and stating that this article
covers the most common causes and fixes.]

## Common causes

This usually happens because:

- [Cause 1 - most frequent, simplest to fix]
- [Cause 2]
- [Cause 3 - least frequent or most complex]

## Fix 1: [Short label for Cause 1]

[One sentence confirming this cause and who it applies to.]

1. [Diagnostic step to confirm this is the cause]
2. [Fix step]
3. [Verification step - what the user sees when it works]

## Fix 2: [Short label for Cause 2]

1. [Diagnostic step]
2. [Fix step]
3. [Verification step]

## Fix 3: [Short label for Cause 3]

1. [Diagnostic step]
2. [Fix step]
3. [Verification step]

## Still not working?

If none of the fixes above resolved the issue, contact support and include:

- Your account email address
- The error message you see (paste the exact text or attach a screenshot)
- Browser name and version, or device and OS if on mobile
- The steps you already tried

Troubleshooting writing checklist

• Title matches how the user describes the problem - not the technical root cause
• Causes listed in order of likelihood (most common first)
• Each fix is self-contained - a user can jump directly to Fix 2 without reading Fix 1
• Every fix ends with a verification step so the user knows whether it worked
• Escalation path at the bottom includes the exact information support needs
• Word count: 200-600 words

FAQ article template

Use for: short, direct answers to common factual questions about a topic

# Frequently asked questions: [topic]

Examples:
  "Frequently asked questions: billing"
  "Frequently asked questions: workspace permissions"

---

## [Question as the user would ask it]

Examples:
  "How do I cancel my subscription?"
  "Can I change my billing email address?"
  "What happens to my data if I downgrade?"

[Direct answer in 1-3 sentences. If the answer requires more than 150 words,
it belongs in a standalone how-to article. Link to it instead.]

---

## [Next question]

[Direct answer.]

---

## [Next question]

[Direct answer.]

FAQ writing rules

• Maximum 10 questions per page. Beyond that, split by subtopic or create individual articles.
• Answer in the first sentence. Never open with context or "Great question!".
• Write questions in first person as the user would ask them: "How do I..." not "How to..."
• Order by frequency (most asked first), not alphabetically.
• If an answer needs a numbered list of steps, convert it to a how-to article and link to it.
• Every FAQ page should have a "Didn't find your answer?" link to contact support at the bottom.

Reference article template

Use for: complete specs, settings tables, limits, permissions matrices, or glossaries

# [Feature or setting name] reference

[One sentence describing what this reference covers and who uses it.]

Example: "This page lists all permission levels in [Product], what each role
can access, and which plan each role is available on."

---

## [Section heading, e.g., "Permission levels"]

| [Column 1] | [Column 2] | [Column 3] |
|---|---|---|
| [Value] | [Description] | [Notes or plan availability] |
| [Value] | [Description] | [Notes] |

---

## [Next section, e.g., "Rate limits"]

| [Column 1] | [Column 2] |
|---|---|
| [Endpoint or action] | [Limit] |

---

## [Next section, e.g., "Glossary"]

**[Term]**
[Definition in 1-2 sentences.]

**[Term]**
[Definition.]

---

## Related articles

- [How-to article that uses these settings]
- [Troubleshooting article for common configuration errors]

Reference writing rules

• Open with a one-sentence scope statement - what the table covers and who it is for.
• Use tables for anything with 3+ rows and 2+ columns. Prose lists are harder to scan.
• Every table needs a header row with clear column names.
• Add a "Notes" or "Plan availability" column whenever a value is conditional.
• Link to the how-to or troubleshooting article that uses these settings - reference articles alone don't tell users what to do.
• Add anchor links (## Section name) to every major section when the page exceeds 500 words.
• Word count: no target - as complete as needed. Use anchor navigation, not length limits.

Style guide: rules that apply to all article types

Help Center Architecture

Detailed patterns for designing help center information architecture across common complexity scenarios: multi-product, multi-role, multilingual, and high-scale knowledge bases.

Single-product help center

The simplest and most common pattern. One product, one audience, one help center.

Recommended category structure

Help Center
  Getting Started
    - Quick start guide
    - System requirements
    - First-time setup
  Account & Settings
    - Profile settings
    - Password and security
    - Notification preferences
  [Core Feature 1]
    - [Subtopic articles]
  [Core Feature 2]
    - [Subtopic articles]
  Billing & Payments
    - Plans and pricing
    - Invoices and receipts
    - Payment methods
    - Cancellation and refunds
  Integrations
    - [Per-integration articles]
  Troubleshooting
    - [Common issues organized by symptom]

Design rules for single-product

• 5-9 top-level categories - Fewer than 5 feels incomplete; more than 9 overwhelms navigation. If you have more than 9, you probably need subcategories.
• Getting Started always first - New users scan left-to-right, top-to-bottom. Put onboarding content where they look first.
• Troubleshooting as a catch-all - Users who cannot find their answer in a feature category will look here. Organize by symptom, not by cause.
• Billing always present - Even if you think billing is simple, users will search for it. Give it its own category.

Multi-product help center

When your company has multiple distinct products that share a help center.

Pattern A: Product-first navigation

Help Center
  [Product A]
    Getting Started
    Features
    Billing
    Troubleshooting
  [Product B]
    Getting Started
    Features
    Billing
    Troubleshooting
  [Shared / Platform]
    Account management
    SSO and security
    API reference

Best for: Products with distinct user bases and minimal overlap. Users of Product A rarely need Product B content.

Pattern B: Topic-first with product filters

Help Center
  Getting Started
    - Getting started with Product A
    - Getting started with Product B
  Account & Settings (shared)
  Billing (shared or per-product)
  [Topic 1]
    - Product A: [article]
    - Product B: [article]
  [Topic 2]
    ...

Best for: Products that share concepts and users frequently use both. Reduces duplication of shared content (account, billing, SSO).

Choosing between patterns

Role-based help center

When different user roles need different content (e.g., admin vs end-user, buyer vs seller, teacher vs student).

Pattern: Role-based sections with shared core

Help Center
  For Admins
    - Admin setup guide
    - Managing users
    - Security settings
    - Billing and invoices
    - Audit logs
  For Team Members
    - Getting started
    - Daily workflows
    - Collaboration features
    - Personal settings
  General
    - Account basics
    - System requirements
    - Contact support

Implementation guidelines

1. Identify the role split - Only create role sections when content divergence is significant (> 30% of articles are role-specific). For minor differences, use callout boxes within shared articles: "Admin only: You can also..."
2. Shared content stays shared - Do not duplicate articles that apply to all roles. Place them in a shared section or link from role sections.
3. Default to the most common role - If 80% of users are end-users and 20% are admins, make end-user content the default experience. Admin content gets its own section.
4. Search should cross boundaries - When a user searches, show results from all sections (with role labels), not just their assumed role.

Multilingual help center

When your knowledge base needs to serve users in multiple languages.

Tier system for translation priority

Not all articles need translation into all languages. Use a tier system:

Architecture decisions

1. Subdomain vs subdirectory vs URL parameter

   • Subdomain: fr.help.example.com - Clean separation, SEO-friendly
   • Subdirectory: help.example.com/fr/ - Easier to manage, shares domain authority
   • URL parameter: help.example.com?lang=fr - Avoid; poor SEO, confusing URLs
   • Recommendation: Subdirectory for most help centers. Subdomain only if you have dedicated localization teams per language.

2. Fallback behavior - When an article is not translated, show the English version with a banner: "This article is not yet available in [language]. Showing the English version." Never show a 404.

3. Language detection - Auto-detect from browser locale, but always provide a manual language switcher. Never force a language based on IP geolocation alone (users travel, use VPNs).

4. Search per language - Search should default to the user's selected language but optionally include English results when the translated knowledge base has coverage gaps.

Translation workflow

1. Author writes article in primary language (usually English)
2. Article is marked "ready for translation"
3. Translation team or service translates Tier 1 content first
4. Translated article is reviewed by a native speaker (not just a translator)
5. Published with cross-links to other language versions
6. When the source article is updated, translated versions are flagged for re-review

High-scale knowledge base (500+ articles)

At scale, standard flat navigation breaks down. Apply these patterns:

1. Faceted navigation

Add filters alongside category navigation:

• Product (for multi-product)
• Role (admin, user, developer)
• Content type (how-to, troubleshooting, reference, video)
• Feature area (subset of categories)

2. Smart search with auto-suggest

At 500+ articles, browsing becomes impractical. Search becomes the primary navigation method. Invest in:

• Auto-complete that suggests article titles as the user types
• Popular/trending queries shown before the user types
• Recent articles shown as suggestions for returning users

3. Content governance model

4. Article lifecycle management

Draft -> Review -> Published -> [Active lifecycle] -> Stale -> Review -> Updated
                                                             -> Archived/Retired

• Published articles get a mandatory review date (3-6 months from publish)
• Stale articles (past review date) are flagged in the CMS dashboard
• Archived articles are removed from navigation and search but preserved with a redirect to the replacement article or a "This article has been retired" notice

5. Content reuse

For shared content that appears in multiple articles (e.g., "How to access admin settings" is referenced in 15 articles):

• Use content snippets / includes if your platform supports them (Zendesk dynamic content, Confluence includes, custom CMS components)
• If not supported, write the shared content in one canonical article and link to it from others. Do not copy-paste.

Migration planning

When moving from one help center platform to another:

Pre-migration checklist

1. Inventory all content - Export every article with metadata: title, category, URL, views, last updated, author, language.
2. Audit before migration - Do not migrate stale or duplicate content. Clean up first; migrate less.
3. Map URL structure - Plan the new URL scheme. Create a redirect map from every old URL to every new URL. 301 redirects are mandatory.
4. Test search - After migration, test the top 50 search queries from your old platform against the new one. Verify results are comparable.
5. Preserve analytics - Set up tracking on the new platform before launch. Establish a baseline for comparison.
6. Communicate the change - Notify users (banner, email) and internal teams (support, sales) about the new help center URL and any navigation changes.

Common migration pitfalls

Search Optimization

Deep dive on making knowledge base content discoverable through search. Covers ranking signals, synonym management, zero-result handling, and platform-specific configuration.

How help center search works

Most help center platforms (Zendesk, Intercom, HelpScout, Freshdesk, Confluence) use a simplified search pipeline:

User query
  -> Tokenization (split into words, remove stop words)
  -> Synonym expansion (map user terms to official terms)
  -> Field-weighted matching (title > tags > body)
  -> Scoring (relevance + popularity + recency)
  -> Results ranked and returned

Unlike web search engines, help center search engines have limited NLP. They rely heavily on exact and partial keyword matches. This means your optimization strategy must focus on putting the right words in the right fields.

Ranking signal weights

Typical weight distribution across help center platforms:

Title optimization tactics

The title is the single most impactful ranking factor. Optimize it by:

1. Mirror user language - Check search analytics for the top 5 query variations for each topic. Use the most common phrasing as the title.
2. Lead with the action - "Reset your password" ranks better for password-reset queries than "Password Management Overview".
3. Include the object - "Export your invoice as PDF" is more specific and searchable than "Export options".
4. Skip articles and filler - "Connect Slack integration" not "How to connect the Slack integration to your workspace".
5. Test with real queries - After updating a title, search for the top 3 user queries for that topic. The article should appear in the top 3 results.

Synonym dictionary

A synonym dictionary maps user vocabulary to your official product terms. Without it, users who search "bill" will not find articles titled "invoice".

Building a synonym dictionary

1. Mine search queries - Export 90 days of search queries. Group queries that target the same article but use different words.
2. Mine support tickets - Look at how users describe problems in ticket subjects and bodies. Note non-standard terms.
3. Map bidirectional pairs - For each official term, list all user variants:

synonyms:
  - canonical: "invoice"
    variants: ["bill", "receipt", "payment record", "statement"]
  - canonical: "sign in"
    variants: ["log in", "login", "sign on", "authenticate"]
  - canonical: "workspace"
    variants: ["organization", "org", "team", "company", "account"]
  - canonical: "integration"
    variants: ["connection", "plugin", "add-on", "app", "connector"]
  - canonical: "subscription"
    variants: ["plan", "membership", "license", "pricing tier"]
  - canonical: "permission"
    variants: ["access", "role", "privilege", "authorization"]

4. Configure in your platform - Most platforms support synonym configuration:
   • Zendesk - Admin > Search > Synonyms
   • Intercom - Settings > Help Center > Search synonyms
   • Freshdesk - Admin > Help Widget > Search settings
   • Confluence - Site admin > Search > Synonyms (Data Center only)

Synonym maintenance

Review and expand the synonym dictionary monthly. New features introduce new jargon gaps. Track zero-result queries as the primary source of missing synonyms.

Zero-result query handling

A zero-result search means the user asked a question your knowledge base cannot answer. Every zero-result query is either a content gap or a search configuration gap.

Weekly zero-result review process

1. Export zero-result queries - Most platforms provide this in search analytics.
2. Classify each query:

3. Prioritize by frequency - A zero-result query searched 50 times per week is more urgent than one searched twice.
4. Track resolution - After fixing, verify the query now returns relevant results. Recheck in the following week's report.

Reducing zero-result rate

Target a zero-result rate below 10%. Healthy knowledge bases typically achieve 3-7%. If your rate is above 15%, prioritize synonym dictionary expansion and content gap filling before any other knowledge base work.

Search result page optimization

The search results page itself affects whether users find answers:

1. Show snippet text - Display the first 150-200 characters of the article body (or a custom meta description) below the title. This helps users evaluate relevance before clicking.
2. Show category breadcrumbs - "Billing > Invoices > Download your invoice" gives context that helps users pick the right result.
3. Highlight matching terms - Bold the matched query terms in the title and snippet to confirm relevance.
4. Offer related suggestions - When results are sparse (1-2 matches), show related articles or categories below the results.
5. Provide a fallback CTA - Below search results, always include: "Can't find what you're looking for? Contact support." This prevents dead-end frustration.

Measuring search effectiveness

Track these search-specific metrics:

A high refinement rate (users searching multiple times) indicates poor result relevance or unclear article titles. A high search-to-ticket rate indicates content gaps or unhelpful articles.

Platform-specific search features

Zendesk Guide

• Supports synonym configuration in admin panel
• Federated search across help center, community, and tickets
• Content cues suggest articles to create based on ticket trends
• Promoted search results (pin specific articles for specific queries)

Intercom Articles

• AI-powered search with natural language understanding
• Article suggestions in the Messenger widget
• Resolution bot can suggest articles before showing search results
• Synonym support in search settings

HelpScout Docs

• Beacon widget embeds search in-app
• Suggested articles based on page URL matching
• Search analytics dashboard with zero-result tracking
• Tag-based search boosting

Freshdesk Knowledge Base

• AI-suggested articles during ticket creation
• Multi-language search with automatic language detection
• Article feedback integration with search ranking
• SEO settings for public-facing knowledge bases

SEO for public knowledge bases

If your help center is publicly accessible and indexed by search engines, apply these additional optimizations:

1. Unique meta titles - Format: "[Article title] | [Product name] Help Center"
2. Meta descriptions - Summarize the article in under 160 characters. Include the primary keyword and a benefit statement.
3. Clean URLs - /help/billing/download-invoice not /help/article/12345
4. Schema markup - Add FAQPage or HowTo structured data where applicable. This enables rich snippets in search results.
5. Internal linking - Link between related articles. This distributes page authority and helps search engines understand topic relationships.
6. Canonical URLs - If the same article appears in multiple categories, set a canonical URL to prevent duplicate content issues.