こんにちは。kickflow CREチームの西山です。
SaaS企業においてテクニカルサポートは、顧客のプロダクトに対する信頼度や愛着といったロイヤリティを左右する重要な一要素です。中でもユーザーがセルフサービス（自己解決）できる質の高いヘルプセンターの提供が、カスタマー・エクスペリエンスの向上には不可欠となっています。
kickflowではヘルプセンターをZendesk Guideで運用していますが、記事の公開に至るまでの運用フローにいくつか課題を感じていました。
今回はこれらの課題を解決するために記事の執筆環境をGitHubに移行し、それによって実現したMarkdownベースの効率的なヘルプ記事の運用についてご紹介します。
これまでのヘルプセンター運用における課題
私が入社以後、ヘルプセンターの記事執筆に関わる中で感じていた課題をいくつかピックアップします。
1. レビューフローの非効率性
Zendesk Guideでヘルプセンターを運用するうえで、最も頭を悩ませていたのがレビューフローです。ヘルプセンターに公開されている記事ページは、機能のアップデートに追従して同一ページを更新していくライフサイクルで運用されることが多いかと思います。もちろん、kickflowも同様です。
Zendeskには『チームパブリッシング』という、記事の公開ステータスの中で変更内容のレビューを行うための仕組みが提供されています。
ただし、契約しているZendeskのプランではチームパブリッシングが利用できなかったため、以下のような方法でレビューを行っていました。
sequenceDiagram
actor 執筆者
participant Slack
actor レビュアー
participant ZendeskGuide
%% 新規に記事を作成する
rect rgb(230, 255, 255)
Note over 執筆者: 【新規に記事を作成する】
執筆者->>ZendeskGuide: 新規記事の下書きを作成
loop レビューがOKとなるまで
執筆者->>Slack: レビュー依頼
Slack-->>レビュアー: 通知
レビュアー->>ZendeskGuide: 下書きを確認・赤字修正またはコメント
レビュアー->>Slack: レビュー返信
Slack-->>執筆者: 通知
執筆者->>ZendeskGuide: 指摘事項を修正
end
執筆者->>ZendeskGuide: 公開処理
ZendeskGuide-->>ZendeskGuide: エンドユーザーに記事が公開される
end
%% 既存の記事の軽微な修正
rect rgb(240, 255, 240)
Note over 執筆者: 【既存の記事の軽微な修正】
執筆者->>Slack: 修正内容と記事URLを共有・レビュー依頼
Slack-->>レビュアー: 通知
レビュアー->>Slack: 確認・レビュー返信
Slack-->>執筆者: 通知
執筆者->>ZendeskGuide: 公開記事を直接修正
end
%% 既存の記事の大幅な修正
rect rgb(255, 245, 235)
Note over 執筆者: 【既存の記事の大幅な修正】
執筆者->>ZendeskGuide: 修正する記事を複製する
ZendeskGuide-->>ZendeskGuide: 下書きで複製
執筆者->>ZendeskGuide: 複製記事に赤字で修正を加える
loop レビューがOKとなるまで
執筆者->>Slack: レビュー依頼
Slack-->>レビュアー: 通知
レビュアー->>ZendeskGuide: 下書きを確認・赤字修正またはコメント
レビュアー->>Slack: レビュー返信
Slack-->>執筆者: 通知
執筆者->>ZendeskGuide: 指摘事項を修正
end
執筆者->>ZendeskGuide: 公開記事に反映
ZendeskGuide-->>ZendeskGuide: エンドユーザーに修正内容が公開される
執筆者->>ZendeskGuide: 複製記事を削除
end
図の通り、記事を新規に追加するか、既存のページを修正するか、そしてその修正ボリュームによって大きく3つの運用フローで成り立っていました。
そしてこのフローにおける問題点は、執筆・レビューに関わるツールが分散されてしまっているのと、時間の経過とともにやりとりや指摘事項が流れてしまう点にありました。また、既存の記事を修正する際に複製された記事を削除する必要もあり、その対応も運用に煩雑さを生んでいました。
2. 執筆体験
執筆するボリュームにも依存しますが、直接Zendesk GuideやSlackに内容を反映するのではなく、一度手元のVSCodeなどの使い慣れたエディタで複数案の文章を下書きしたあとに、適宜反映する運用をしていました。ワンステップ挟むことにはなりますが、この方が直接修正するよりは執筆体験がよいと個人的には感じていました。
また、複数の記事を横断して一括置換したいようなケース（例えば機能名や表記の一括変更など）の対応もやりづらく、Zendesk Guide上でキーワード検索をして、ヒットするページをひとつずつ開いてチェックするという対応が必要でした。このような対応の頻度は多くはないですが、実際に修正する際の体験があまりよくないため、解消したいひとつの課題ではありました。
解決策の設計思想
冒頭ですでにネタバレをしていますが、レビューフローをプルリクエスト（以下、PR）ベースで行うために記事の管理をGitHubに移行して、記事はMarkdownで執筆できるようにしました。
なぜGitHubなのか
最大の理由は、Git/GitHubによるファイル（ソースコード）の管理はプロダクト開発文脈ではごく一般的な方法で、そのエコシステムに乗ることができるためです。GitHubにコンテンツ管理を寄せることで、変更の差分確認、PR上でのコメントによる議論や承認プロセスなど、確立されたレビューの仕組みを導入できます。
ただし、主に記事を執筆するのはテクニカルサポートやデザイナーといった非エンジニア職が担当するため、Gitの導入がハードルになる可能性がありました。この点については、GitHubのWeb UIを活用し、Gitのコマンドラインを意識することなく記事の作成・編集ができる手順を整備することで解決しました。
なぜMarkdownなのか
kickflowでは、社内ドキュメントをesaで管理していることもあり、チームの全員がMarkdownを取り扱うことには慣れているため、Markdownで執筆すること自体の学習コストはほぼゼロでした。
また、Markdownであればtextlintによる文章校正の導入などもやりやすく、仕組みによるレビューコストの削減も見込めました。人の目だけでは見落としがちな表記揺れや文法エラーを自動的に検出できるため、レビュアーはより内容の品質に集中することが期待できます。
さらに、MarkdownはAIとの親和性が高く、RAGの構築にも適しています。プレーンテキストベースの構造化された文書は、ベクトル化や検索処理がしやすく、将来的なAIを活用したヘルプデスク機能の導入においてもメリットになると考えました。
技術的な観点では、Zendesk Guideは内部的に記事をHTMLに変換した状態で保持しているため、SSG（静的サイトジェネレーター）のような仕組みでHTMLに変換してZendeskに反映できればよいと考えました。SSGはMarkdown→HTMLに変換されるものが多くあるので実装もしやすく、その作り込みだけでレビューフローの改善などが見込めました。
どうやったか
Zendesk Guideの記事をMarkdownで扱う仕組みを作った
手前味噌にはなりますが、MarkdownをHTMLに変換してZendesk Guideに反映する zgsync というCLIツールを開発しました。本記事では詳しく取り扱いませんが、リポジトリのREADMEでどのようなことができるか掴んでもらえると思うので興味があればぜひご覧ください。
このツールではZendesk Help Center REST APIのうち、ArticlesとTranslationsを以下のようなFrontmatter付きのMarkdownで取り扱えます。
実際のページのMarkdownファイル（抜粋）
--- title: フォームの自動計算フィールドで使用可能な変数や関数を教えて下さい locale: ja draft: false outdated: false section_id: 360007939953 source_id: 360053280013 html_url: https://support.kickflow.com/hc/ja/articles/360053280013 --- :::{.block .notice} 変数、演算子、関数の仕様について、必ずご一読ください。 ::: :
GitHubとこのCLIツールを組み合わせることで運用上の課題をクリアしたかったのですが、前述の通り、主に記事を執筆するのは非エンジニア職のメンバーになります。このCLIツールの利用を強いるのではなく、GitHub Actionsでツールをラップすることで、運用ハードルを下げています。
GitHub Actionsで複雑な操作をカバー
管理をGitHub + Markdownに寄せたことで「新規記事の下書き」を作成するにはZendeskに記事を作成して、その記事に対応するMarkdownファイルをGitHub上にコミット・プッシュしてPRを作成する必要があります。
以下のようなworkflow_dispatchで呼び出し可能なワークフローを作成して、Zendesk Guideに記事を作成するのに必要な情報を入力できるようにしています。
name: 01.下書きを作成する
on:
workflow_dispatch:
inputs:
title:
type: string
description: 記事のタイトル
required: true
section:
type: choice
description: 記事の階層
options:
- "[Help] 申請者・承認者向け > 初期設定 (8644462439321)"
- "[Help] 申請者・承認者向け > チケットの検索・閲覧 (360007745293)"
- "[Help] 申請者・承認者向け > チケットの作成 (360007745273)"
:
- "[FAQ] 申請者・承認者向け > チケットの閲覧 (360007939893)"
- "[FAQ] 申請者・承認者向け > チケットの作成 (360007939933)"
- "[FAQ] 申請者・承認者向け > チケットの承認・差し戻し (360007881114)"
- "[FAQ] 申請者・承認者向け > 通知（メール通知・チャット通知） (4406930989465)"
:
required: true
permissionGroupID:
type: choice
description: この記事を編集・公開できるユーザー
options:
- エージェントと管理者 (1234567)
- 管理者 (1234568)
required: true
userSegmentID:
type: choice
description: 表示対象ユーザー
options:
- 全員
- 管理者・エージェント (123456789010)
- サインインユーザー (123456789011)
required: false
これであれば、非エンジニアの執筆者でも戸惑うことなくGitHubから操作ができます。
上記のActionの定義は一部の抜粋ですが、実際のワークフローの定義では選択された項目を必要に応じてシェルでパースして、以下のように以降のステップで実行されるコマンドのオプションに指定できるようにしています。
- name: create draft article
run: |
zgsync empty \
--config config.yaml \
--title "${{ github.event.inputs.title }}" \
--section-id ${{ steps.parse_inputs.outputs.SECTION_ID }} \
--save-article \
--with-section-dir
shell: bash
これ以外の操作についても任意のGitHub Actionsを実行することで、コマンドを実行することなく処理できるようになっています。
github.dev エディター
GitHubリポジトリからファイルをローカル環境にクローンしようとするとGit感が色濃く出てしまうため、少しでもその色を薄めるためにオンラインの github.dev エディターを使用して執筆することにしてマニュアルを手厚く整備しました。github.dev エディター自体がVSCodeと変わらないUIなので、VSCode拡張を使ったGit操作説明でGitHubによる執筆のハードルはクリアできたと思います。
新しい執筆フロー
新しいヘルプセンターにおける執筆フローは以下のようになっています。
sequenceDiagram
actor 執筆者
participant GitHub
actor レビュアー
participant ZendeskGuide
alt 新規に記事を作成
%% 新規記事の作成フロー
rect rgb(230, 255, 255)
Note over 執筆者: 【新規記事を作成】
執筆者->>GitHub: GitHub Actions を実行
GitHub->>ZendeskGuide: 下書き記事を作成
GitHub->>GitHub: Markdownファイルをコミット
GitHub->>GitHub: PRを作成
執筆者->>GitHub: Markdownを修正・執筆
end
else 既存の記事を修正
%% 既存記事の修正フロー
rect rgb(240, 255, 240)
Note over 執筆者: 【既存記事を修正】
執筆者->>GitHub: 既存Markdownを修正・執筆
執筆者->>GitHub: コミットしてPRを作成
end
end
%% textlintやAIによるレビュー
rect rgb(255, 245, 235)
Note over 執筆者: 【自動レビュー】
GitHub->>GitHub: textlintやAIによるレビュー
執筆者->>GitHub: 必要に応じて修正
end
%% レビュー・マージフロー
rect rgb(255, 245, 235)
Note over 執筆者: 【レビューとマージ】
執筆者->>レビュアー: PRのレビューを依頼
レビュアー->>GitHub: レビュー
alt 指摘あり
loop 修正→再レビュー
執筆者->>GitHub: 修正を加える
執筆者->>レビュアー: 再レビュー依頼
レビュアー->>GitHub: 再レビュー
end
else 問題なし
執筆者->>GitHub: PRをマージ
GitHub->>ZendeskGuide: 変更を反映（自動）
end
end
レビューがGitHubのPRに集約されたことで、今までにはなかったtextlintやAIによるレビューを組み込むことができ、総合してスッキリとした運用フローが構築できたと思います。
まとめ
ヘルプセンターのライティングフローをGitHubに移行することで、レビューの効率化、執筆体験の向上、品質管理の自動化などを実現できました。特に、既存のソフトウェア開発ワークフローに乗ることで、新たな学習コストを最小限に抑えながら、大幅な改善を実現できたことが大きな成果でした。
ヘルプセンターの執筆に同じような課題を抱える方の参考になれば幸いです。
kickflowでは、私たちと一緒にプロダクト開発を推進してくれる仲間を募集しています。業務の改善や開発効率化などに興味のある方は、ぜひ採用サイトをご覧ください。
