knowledge-base-article-writing

# Knowledge Base Article Writing

Produce polished help center articles and FAQ entries that deflect support tickets by giving customers clear, self-serve answers. This skill turns support ticket patterns, product changes, and common questions into structured articles optimized for readability, search, and scannability, following documentation best practices for step-by-step guides, troubleshooting flows, and reference material.

## Workflow

1. **Identify topic from support data** — Mine support ticket trends, search analytics (what customers search for but don't find), and CSM feedback to find the highest-impact topics. Prioritize by ticket volume (articles addressing the top 10 question clusters deflect the most tickets), topic complexity (complex topics benefit most from written guides), and recency (new features or recent changes need documentation immediately).

2. **Research the solution** — Gather the authoritative answer from engineering docs, internal wikis, product specs, and subject matter experts. Test the workflow yourself end-to-end in the product to verify accuracy. Document the exact UI text, button labels, and navigation paths as they appear in the current product version. Note any prerequisites, required permissions, or plan-tier restrictions.

3. **Structure the article** — Follow a consistent template: **Title** (action-oriented, matches how customers search), **Summary** (1-2 sentence answer for scanning), **Prerequisites** (what the reader needs before starting), **Steps** (numbered, one action per step, with expected outcome), **Troubleshooting** (common errors and their fixes), and **Related Articles** (links to adjacent topics). Keep the hierarchy flat — use H2 for major sections and H3 sparingly.

4. **Add visual aids and code examples** — Include screenshots for UI-heavy workflows (annotated with numbered callouts matching the steps), code snippets for API or CLI workflows (with language tags, copy buttons, and expected output), and diagrams for architecture or flow explanations. Every image should have alt text. Every code block should be tested and runnable.

5. **Optimize for search** — Write the title using the exact phrasing customers use (check search analytics). Front-load keywords in the first sentence. Add metadata tags for category, product area, and plan tier. Include common alternate phrasings as a "Also known as" line or in the article metadata. Keep URLs clean and human-readable.

6. **Review for accuracy and clarity** — Have a subject matter expert verify technical accuracy. Run a readability check targeting grade 8 reading level. Ensure every step is testable by someone with no prior context. Check that screenshots match the current UI. Validate all links. Set a review-by date (typically 90 days or on next product release affecting the topic).

## Usage

Describe the article topic, target audience, and any specific details to include. The agent writes a complete, publish-ready article.

```
Write a help center article for "How to set up SSO with SAML." Target audience
is IT admins. Our product supports Okta, Azure AD, and OneLogin. Include
troubleshooting for common SAML errors.
```

## Examples

### Example 1: How-to article — SSO with SAML setup

**Input:** SSO/SAML setup guide for IT administrators.

**Output:**

---

**How to Set Up Single Sign-On (SSO) with SAML**

Enable SAML-based SSO so your team can sign in using your company's identity provider. Supported providers: Okta, Azure AD, and OneLogin.

**Prerequisites**
- Admin role in your account (Settings → Team → Roles shows "Admin" next to your name)
- Access to your identity provider's admin console
- Your account must be on the Enterprise plan

**Steps**

1. Go to **Settings → Security → Single Sign-On** and click **Configure SSO**.

   *[Screenshot: Settings page with Security tab highlighted and SSO section visible]*

2. Select your identity provider from the dropdown: **Okta**, **Azure AD**, or **OneLogin**.

3. Copy the values shown on screen — you will need these in your identity provider:
   - **ACS URL:** `https://app.example.com/auth/saml/callback`
   - **Entity ID:** `https://app.example.com/saml/metadata`
   - **RelayState:** leave blank unless using a custom landing page

4. In your identity provider's admin console, create a new SAML application using the values from step 3.

   **Okta:** Applications → Create App Integration → SAML 2.0 → paste ACS URL and Entity ID.

   **Azure AD:** Enterprise Applications → New Application → Create your own → SAML → Basic SAML Configuration → paste values.

   **OneLogin:** Applications → Add App → SAML Custom Connector → Configuration → paste values.

5. Download the **Federation Metadata XML** file from your identity provider and upload it on the SSO configuration page.

6. Set the required attribute mappings:
   ```
   email    → user.email       (Required)
   firstName → user.firstName  (Required)
   lastName  → user.lastName   (Required)
   role      → user.role       (Optional — maps to app roles)
   ```

7. Click **Test Connection**. A new browser tab opens. Sign in with your identity provider credentials. If successful, you'll see "SSO connection verified."

8. Toggle **Enforce SSO** to require all team members to sign in via your identity provider. Non-SSO login will be disabled after a 24-hour grace period.

**Troubleshooting**

| Error | Cause | Fix |
|-------|-------|-----|
| "SAML response signature invalid" | Metadata XML is outdated or from the wrong app | Re-download the metadata XML from your IdP and re-upload it |
| "User not found" | Email in SAML assertion doesn't match any account email | Verify the email attribute mapping in your IdP sends the user's primary email |
| "Clock skew detected" | Server time difference between IdP and our service exceeds 5 minutes | Ensure your IdP server's NTP is synced. We allow a 5-minute skew tolerance |
| "Audience mismatch" | Entity ID in your IdP doesn't match the value from st