name: knowledge-base-article-writing description: 基於支援資料、產品文件和常見客戶問題，撰寫清晰、可檢索的幫助中心文章與 FAQ 條目。 license: MIT metadata: author: community version: 1.0.0

知識庫文章撰寫

產出打磨精良的幫助中心文章和 FAQ 條目，通過為客戶提供清晰、自助式的答案來分流支援工單。本技能將支援工單模式、產品變更和常見問題轉化為結構化的文章，針對可讀性、可檢索性和可掃描性進行最佳化，並遵循文件最佳實踐——分步指南、故障排查流程與參考資料。

工作流

1. 從支援資料中識別主題 — 挖掘支援工單趨勢、搜尋分析（客戶搜尋卻找不到的內容）和 CSM 反饋，找出影響最大的主題。按工單量優先（覆蓋前 10 大疑問簇的文章分流的工單最多）、主題複雜度（複雜主題從書面指南中獲益最多）和新近度（新功能或近期變更需要立即文件化）。

2. 研究解決方案 — 從工程文件、內部 wiki、產品規格和主題專家處收集權威答案。在產品中親自端到端測試該工作流以驗證準確性。記錄當前產品版本中出現的確切 UI 文本、按鈕標籤和導航路徑。註明任何前置條件、所需許可權或套餐層級限制。

3. 構建文章結構 — 遵循一致的模板：標題（以行動為導向，匹配客戶搜尋方式）、摘要（1–2 句用於掃描的答案）、前置條件（讀者開始前需要什麼）、步驟（編號，每步一個動作，含預期結果）、故障排查（常見錯誤及其修復）、相關文章（相鄰主題的連結）。保持層級扁平——主要章節用 H2，H3 謹慎使用。

4. 新增視覺化輔助與程式碼示例 — 對 UI 密集工作流附截圖（用與步驟對應的編號標註），對 API 或 CLI 工作流附程式碼片段（帶語言標籤、複製按鈕和預期輸出），對架構或流程說明附圖表。每張圖片都應有替代文本。每個程式碼塊都應經過測試且可執行。

5. 針對搜尋最佳化 — 使用客戶實際使用的確切措辭撰寫標題（檢查搜尋分析）。在首句中前置關鍵詞。為類別、產品區域和套餐層級新增元標籤。將常見的替代表述作為"又稱"一行或文章後設資料中。保持 URL 簡潔、人類可讀。

6. 審查準確性與清晰度 — 請主題專家核實技術準確性。運行針對八年級閱讀水平的可讀性檢查。確保每步都能被無任何先驗上下文的人測試。檢查截圖是否與當前 UI 匹配。驗證所有連結。設定複核日期（通常為 90 天，或下次影響該主題的產品釋出時）。

使用方式

描述文章主題、目標受眾，以及要包含的任何具體細節。Agent 會寫出一篇完整、可直接釋出的文章。

為我們寫一篇幫助中心文章："如何用 SAML 配置 SSO。" 目標受眾是 IT 管理員。
我們的產品支援 Okta、Azure AD 和 OneLogin。包含常見 SAML 錯誤的故障排查。

示例

示例 1：操作指南文章 — SAML 的 SSO 配置

輸入： 面向 IT 管理員的 SSO/SAML 配置指南。

輸出：

如何用 SAML 配置單點登入（SSO）

啟用基於 SAML 的 SSO，讓你的團隊可以使用公司的身份提供商登入。支援的提供商：Okta、Azure AD 和 OneLogin。

前置條件 - 你賬戶中的 Admin 角色（Settings → Team → Roles 中你的名字旁顯示"Admin"） - 可訪問你的身份提供商的管理控制台 - 你的賬戶必須在 Enterprise 套餐上

步驟

1. 前往 Settings → Security → Single Sign-On 並點選 Configure SSO。

[截圖：Settings 頁面，Security 標籤頁高亮，SSO 區域可見]

1. 從下拉選單中選擇你的身份提供商：Okta、Azure AD 或 OneLogin。

2. 複製螢幕上顯示的值——你在身份提供商處將需要這些值：

3. ACS URL： https://app.example.com/auth/saml/callback
4. Entity ID： https://app.example.com/saml/metadata

5. RelayState： 留空，除非使用自定義落地頁

6. 在身份提供商的管理控制台中，使用第 3 步的值建立一個新的 SAML 應用。

Okta： Applications → Create App Integration → SAML 2.0 → 貼上 ACS URL 和 Entity ID。

Azure AD： Enterprise Applications → New Application → Create your own → SAML → Basic SAML Configuration → 貼上值。

OneLogin： Applications → Add App → SAML Custom Connector → Configuration → 貼上值。

1. 從身份提供商處下載 Federation Metadata XML 檔案，並上傳到 SSO 配置頁面。

2. 設定所需的屬性對映： email → user.email (Required) firstName → user.firstName (Required) lastName → user.lastName (Required) role → user.role (Optional — maps to app roles)

3. 點選 Test Connection。新瀏覽器標籤頁開啟。用你的身份提供商憑據登入。若成功，將看到"SSO connection verified."

4. 切換 Enforce SSO 以要求所有團隊成員通過你的身份提供商登入。非 SSO 登入將在 24 小時寬限期後停用。

故障排查

相關文章 - 管理團隊角色與許可權 - 配置 SCIM 使用者預配 - 配置多因素身份驗證

示例 2：FAQ 條目 — 賬單問題

輸入： 涵蓋套餐變更、發票和退款的常見賬單 FAQ。

發現更多技能外掛，請訪問7w4.net。

輸出：

賬單 FAQ

關於套餐、發票、付款和退款最常見問題的答案。

如何升級或降級我的套餐？

前往 Settings → Billing → Plan 並點選 Change Plan。選擇新套餐並確認。升級立即生效，你將按當前計費週期剩餘天數按比例計費。降級在下個計費週期開始時生效——在此之前你仍可使用當前套餐的功能。

在哪裡可以找到我的發票？

所有發票都在 Settings → Billing → Invoice History。點選任意發票檢視或下載 PDF。每筆扣費後 24 小時內，發票也會通過郵件傳送給在檔的賬單聯絡人。

如何更新付款方式？

前往 Settings → Billing → Payment Method 並點選 Update。我們接受 Visa、Mastercard、American Express 和 ACH 銀行轉賬（僅年度套餐）。你的新付款方式將用於所有未來扣費。

我可以獲得退款嗎？

如果你不滿意，我們在任何扣費後 14 天內提供全額退款。超過 14 天后，我們發放用於未來計費的比例抵扣。要申請退款，請傳送郵件至 billing@example.com，附上你的賬戶郵箱和發票號。退款在 5–7 個工作日內處理。

如果付款失敗會怎樣？

我們在第 1、3、7 天重試失敗的付款。每次失敗後你都會收到郵件通知。如果 14 天內未解決，你的賬戶將降級到免費層級。你的資料保留 90 天——隨時升級以恢復完整訪問。

你們提供年度賬單折扣嗎？

是的。在 all paid plans 上，年度賬單相比月度賬單節省 20%。隨時可從 Settings → Billing → Plan 切換到年度賬單——選擇"Annual"，你的節省會立即生效，並對任何剩餘的月度餘額按比例抵扣。

相關文章 - 理解你的發票行專案 - 設定 ACH 銀行轉賬付款 - 管理多個計費賬戶

最佳實踐

• 標題使用匹配客戶搜尋方式的問題或行動短語——"如何配置 SSO"勝過"SSO 配置指南"，因為客戶用自然語言搜尋。
• 一篇文章，一個主題。如果一篇文章涵蓋兩個不同的工作流，就拆分它。搜尋"匯出資料"的客戶不應落到同時涵蓋"匯入資料"的頁面——即便它們對你來說似乎相關。
• 每篇文章都以一句直接回答問題的摘要開頭。客戶是掃描而非閱讀——如果答案在第一行，即使他們不再往下讀也能獲得價值。
• 使用與 UI 標籤完全一致的術語。如果按鈕顯示"Configure"，不要在文章中寫"Set Up"。文件與 UI 的不一致會造成困惑並損害信任。
• 在每篇文章上包含"最後驗證"日期，並在其覆蓋的產品區域在變更日誌中收到更新時建立自動提醒。
• 用兩個指標跟蹤文章效果：搜尋到檢視率（客戶能找到它嗎？）和分流率（檢視後 30 分鐘內客戶是否開了工單？）。

邊緣情況

• 撰寫與釋出之間產品 UI 發生變化 — 始終最後再截圖，在文章文本定稿之後。在圖片替代文本中包含產品版本號，以便在審計時更容易識別過時的截圖。
• 僅在特定套餐可用的功能 — 在頂部新增醒目橫幅："此功能在 Pro 和 Enterprise 套餐上可用。"不要把套餐限制埋在第 4 步之後，在讀者已投入時間之後才出現。
• 多語言知識庫 — 先以英文撰寫規範文章，再進行本地化。不要未經人工審查就機器翻譯併發布——技術術語和 UI 標籤必須與本地化的產品介面匹配。
• 已棄用的功能 — 不要刪除已棄用功能的文章。新增帶 sunset 日期的棄用橫幅，並連結到替代文章。使用舊套餐的客戶可能仍需要舊文件。
• 來自多個來源的衝突資訊 — 當內部文件與產品的實際行為不一致時，產品行為才是事實來源。在產品裡測試，記錄實際發生的情況，如果行為有誤則提交 bug。

這個Skill質量不錯，提供了清晰的寫作流程和豐富的示例參考，能夠幫助你寫出結構完整、格式規範的知識庫文章。優點是示例詳細、最佳實踐實用；不足之處是引導方式較為單一，缺少互動迭代機制，寫作質量保障方法也不夠具體。對於需要撰寫幫助文件的使用者來說，是一個有參考價值的參考模板，但使用體驗還有最佳化空間。