knowledge-base-article-template

name	knowledge-base-article-template
enabled	true
description	Use when performing knowledge base article template — template for writing IT support knowledge base articles covering problem description, step-by-step resolution, troubleshooting tips, and related resources. Provides a standardized format for documenting solutions so helpdesk agents and end users can find and follow resolutions consistently.
required_connections	[{"prefix":"itsm","label":"ITSM Tool (ServiceNow, Freshservice, etc.)"}]
config_fields	[{"key":"article_title","label":"Article Title","required":true,"placeholder":"e.g., How to Connect to Corporate VPN on macOS"},{"key":"category","label":"Category","required":true,"placeholder":"e.g., Network, Email, Software, Hardware, Access"},{"key":"audience","label":"Target Audience","required":true,"placeholder":"e.g., End Users, Helpdesk Agents, IT Admins"},{"key":"related_tickets","label":"Related Ticket IDs (for reference)","required":false,"placeholder":"e.g., INC-1234, INC-5678"}]
features	["HELPDESK"]

Knowledge Base Article Template

Article Metadata

ARTICLE DETAILS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Title:           {{ article_title }}
Category:        {{ category }}
Audience:        {{ audience }}
Related Tickets: {{ related_tickets }}
Author:          [author name]
Created:         [date]
Last Updated:    [date]
Review Date:     [date + 6 months]
Status:          [ ] Draft / [ ] In Review / [ ] Published

Article Structure

Use the following standardized structure for all KB articles:

---

{{ article_title }}

Category: {{ category }} | Audience: {{ audience }}

Applies To

• [List the systems, applications, or hardware this article applies to]
• [Include version numbers where relevant]
• [Specify operating systems if applicable]

Symptoms / Problem Description

Describe the issue the user is experiencing in clear, non-technical language (if audience is end users):

• [Symptom 1 — what the user sees or experiences]
• [Symptom 2 — error messages, if any, in exact wording]
• [Symptom 3 — when/how the issue typically occurs]

Cause

Brief explanation of why this issue occurs (optional for end-user articles, recommended for agent/admin articles):

• [Root cause or common trigger]

Resolution

Step-by-step instructions:

1. [Action verb] [what to do]

   • [Detailed sub-step if needed]
   • [Include screenshot placeholder: [Screenshot: description]]

2. [Action verb] [what to do]

   • [Detailed sub-step]
   • Expected result: [what should happen]

3. [Action verb] [what to do]

   • [Detailed sub-step]

4. Verify the fix

   • [How to confirm the issue is resolved]
   • Expected result: [what success looks like]

Alternative Solutions

If the primary resolution does not work:

1. Alternative approach 1: [brief description]
2. Alternative approach 2: [brief description]

Troubleshooting Tips

• [Common mistake to avoid]
• [Additional check if standard resolution fails]
• [Edge case that requires different handling]

If This Does Not Resolve the Issue

• Contact the IT helpdesk at [contact info]
• Reference this article: {{ article_title }}
• Include the following information in your ticket:
  • [What info to include]
  • [Error messages]
  • [Steps already attempted]

Related Articles

• [Link to related KB article 1]
• [Link to related KB article 2]

---

Writing Guidelines

Dos

• Write in clear, simple language appropriate for {{ audience }}
• Use numbered steps for procedures (not paragraphs)
• Include exact menu paths: Settings > Network > VPN
• Show exact error messages users might see
• Include screenshots for complex UI steps
• Test all procedures before publishing
• Set a review date (every 6 months)

Don'ts

• Don't assume technical knowledge (for end-user articles)
• Don't use jargon without explanation
• Don't combine multiple topics in one article
• Don't include temporary workarounds without marking them clearly
• Don't publish without peer review

SEO / Searchability

• Use keywords users would search for in the title
• Include common alternate terms (e.g., "WiFi" and "wireless")
• Include error message text verbatim for search matching

Review & Publishing Workflow

1. Author drafts article using this template
2. Peer review by another agent/engineer
3. Technical accuracy verified (steps tested)
4. Approved by knowledge base manager
5. Published to appropriate audience (internal/external)
6. Added to relevant categories and tagged
7. Scheduled for periodic review

Counter-Rationalizations

Shortcut	Counter	Why
"We can skip some steps for this case"	Adapt the workflow steps, don't skip them	Skipped steps are where incidents and oversights originate
"The user seems to already know what to do"	Complete all workflow phases with the user	The workflow catches blind spots that experience alone misses
"This is a minor case, full process is overkill"	Scale the process down, don't turn it off	Minor cases become major when unstructured; the process scales, not disappears
"I'll fill in the details later"	Complete each section before moving on	Deferred details are forgotten; real-time capture is more accurate
"The template output isn't necessary"	Always produce the structured output format	Structured output enables comparison, audit trails, and handoff to other teams

Output Format

Generate a complete KB article following the structure above, ready for review and publishing.