前々から、ヘルプのバージョン管理をしたいと思っていたのですが、なかなか手が回らず放置していたところ、フリーランスで編集者をやっていた者がCSメンバーとして入社したので、それを機に、本格的に準備を進めて、今年頭から、運用を始めてみました。
1ヶ月ほど運用してみて、なかなか良い感じなので、紹介したいと思います。
ちなみに、boardという見積書や請求書作成・業務管理・経営管理などができるSaaSのヘルプです。
なお、仕組みとしては、GithubのプルリクエストとWebhookを使っているだけなので、何か特別なことをやっているわけではなく、ソースコードのレビューやデプロイと同じようなことをヘルプ記事にも適用したという感じです。
これまでのboardのヘルプ
現在357記事あり、通常のヘルプが226記事、FAQが131記事あります。
通常のヘルプは、機能・仕様や効率的な使い方などの説明で、長めの記事が多いです。FAQは、問い合わせが多い質問を中心に、簡単な説明＋ヘルプへの誘導という簡潔な内容です。
これまでのヘルプは、 WYSIWYGなHTMLエディタを組み込んだ管理画面を用意して、そこから登録していました。そのため、本文データはHTMLで、DBに保存されていました。
ヘルプに関しては、ユーザの方から「内容が充実していてほとんどヘルプだけで解決する」などのコメントを頂くことも度々あり、実際、有料導入1800社以上いて、CS二人で余裕を持って回せているので、かなり自己解決の役には立っているのではないかなと思っているのですが、今回の取り組みで、より安定した品質と、編集を通すことで読みやすさを改善して、さらにレベルアップさせていきたいと思っています。
今回の方針
バージョン管理を行う方法として、管理画面側に自前で実装する方法も考えられますが、今回、バージョン管理だけでなく編集・校正の運用をしたく、これをGithubのプルリクエストでやりたかったので、管理画面での自前実装はせず、Githubで管理することを軸に考えました。
そのためには、まずは、現在DBに入っているヘルプのデータをファイルにしていく必要があります。
ヘルプデータをファイルにするにあたって、HTMLからMarkdownにすることを検討しました。ヘルプなので、それほど複雑な表現は必要ないし、HTMLタグがない方が差分も見やすいかなと。
ただ、以下の理由で、今回は、HTMLのままにすることにしました。
- できるだけ工数は最小限に抑えたく、ヘルプの表示側の実装は変更したくない
- データ形式の変更に伴うテスト・内容のチェックなどの時間を確保するのが難しい
- 表形式で表示している箇所があり、Markdownのテーブルだと厳しかった
ということで、今回は、これまで登録されていたヘルプのHTMLデータはそのままにし、ヘルプの表示側（board上でのヘルプ）の実装は変えず、その手前でバージョン管理をしていく、という方針で考えました。
今回の仕組みと運用方法
ざっくり図で表すとこんな感じです。
バージョン管理はGitを使い、校正のフローはGithubのプルリクエストを使います。
あとは、よくあるシステムのデプロイと同じように、所定のブランチにマージされたら、自動的にステージング環境・本番環境にそれぞれ反映される仕組みです。
現時点ではヘルプの運用に関わるのは、僕と@note103の二人です。@note103 はこれまで10年ほどフリーランスで編集者をやっていたので、僕がヘルプを書き、彼が編集をするという役割分担です。
なぜか普通にgitを使える編集者なので、わりとそれに依存した仕組みではあります。
ちなみに、長く編集者をやっていた彼が入社した経緯は本人のブログをどうぞ。
運用フローは主に以下の2パターンです。
＜新規のヘルプ＞
- 僕が新規のヘルプを書いて、Githubでプルリクエスト
- @note103が編集・校正
- プルリクエストをマージしてステージング環境へ自動反映→最終チェック
- masterにマージして本番環境へ自動反映
＜既存ヘルプの修正＞
- @note103が気づいた点を随時修正してプルリクエスト
- 僕が内容に間違いがないかをチェック
- プルリクエストをマージしてステージング環境へ自動反映→最終チェック
- masterにマージして本番環境へ自動反映
上記のように、Gihtubのプルリクエストを使って運用していくため、現在、DBに入っているヘルプのデータをファイルにする必要があります。
ただ、本文のHTMLだけでなく、タイトル・メタ情報・OGPなど、本文以外の情報もあります。
そこで、以下のようにしました。
- 本文データはそのままDBから取り出して、記事ごとにHTMLファイルにする
- それ以外の情報は、YAMLファイルにし、1記事ごとに本文のHTMLと対になるように生成
記事ごとに、本文のHTMLファイルと、それ以外の情報を持ったYAMLファイルをセットで管理するような形です。
本文のHTMLだけファイルを分けたのは、単独のファイルにすることで、HTMLエディタで編集ができたり、Middlemanに組み込んで、ローカル環境で、実際のスタイルを当てて見栄えを確認しながら編集できるようにするためです。
ちなみに、文章をGitで管理するということに関しては、「k16's note: 執筆・編集のためのGit（GitHub）ワークフローを考えてみた」がとても勉強になりました。
ヘルプの場合は1つ1つが大きな文章ではなく、文章の骨組みの大幅な変更などはあまりないので、上記の記事にある「じっくり読まなければ何となくいい感じ」からスタートしているイメージの運用です。
この仕組みのメリット
バージョン管理という点では、ブランチを切れたり、簡単に戻せたり、いつでも過去の履歴を確認できるなど、ソースコードのバージョン管理と同じようなメリットがあります。
また、編集をプルリクエストに乗せることで、管理しやすく、差分も確認しやすいので、編集の運用がスムーズです。
ここまでは想定通りなのですが、実際に運用してみて、Githubからのwebhookでヘルプのデプロイができるのがとても良いなと。
ステージング環境でしっかり確認したものをそのまま反映できるので、本番に反映するにあたってオペレーションミスがありません。
システムのデプロイでは当たり前なんですけど、ヘルプでも、本番環境のものは当然ユーザさんの目に触れるものだし、その品質管理は重要だと思っていて、そういう点で、しっかり確認できたものを、人手によるミスがない方法で反映できるというのはとても良いなと思いました。
また、2/10に全体的なデザインが少し変わったことで、スクリーンショットを全て差し替える必要があったのですが、200以上の記事のスクリーンショットを全部差し替えて行くという作業を、管理画面のHTMLエディタでやっていたら、たぶんいくつもミスがあったのではないかなと思います。
ただ、この仕組みのおかげで、スクリーンショット差し替え用のブランチで事前に準備しておき、事前にステージング環境で入念に確認し、リリース時に、ヘルプの方もmasterにマージして自動的に反映されるという、とても楽な方法で一括反映できました。
ちなみに、約150記事を本番に反映した際、3分程度で終わりました。
この仕組みのデメリット
実際運用してみて、やはり管理画面から直接編集していた時に比べて手間はかかるので、「ちょっと修正したい」という時に面倒だなとは思います。
例えば、開発ロードマップの状況を更新するだけの時とか。
あとは、gitに依存しているので、うちの場合は、普通にgitを扱える編集者だったので良かったですが、ここはちょっとハードルにはなるかもしれないです。
編集者視点での感想
せっかくなので、@note103に感想を聞いてみました。
■履歴・記録を残せる
一番良いと思うのは、履歴を残せることですね。というのも、日本語の修正・編集って一発で決まるものばかりではなくて、あーでもないこーでもない、と迷いながらやることが多いので、一回決まったと思っても、「やっぱり前のが良かったかも・・」となりやすいです。
そういうときに、記録が残らない方法だと前の内容を参照することは難しいですが、バージョン管理ができると「いつでも戻れる」という前提があるので、逆に気軽にサクサク直していけるという、心理的負担が軽くなる効果があると思います。
■複数人で共有・分担できる
あとは、やっぱり修正した内容（差分）を他人が確認できる、ということも大きな利点ですね。これの良いところは、単に「修正内容を共有できる」というだけのことではなくて、「直す人」と「本番環境に反映する人」を分けられるということが重要だと思います。
実際の話、日本語の修正なんてある意味誰でもできるわけですが（とくにタイポの修正など）、でも本番に反映する作業は誰がやっても良いわけではないので、「直す人」がコミット＆プッシュして、「反映する人」が差分を見てマージする、という分担の流れはとても効率が良いと思います。
それに関連して、もう一つ地味に大きいのが、自分でも「どこを直したのか」を確認できるのが良いですね。とくに1つのファイルにいくつも修正がある場合、自分がどこを直したかすべて覚えておくことはできないので、後から自分自身で修正箇所をチェックできるというのはメリットだと思っています。
■作業がラク
あとはテキストファイルで管理されているので、普段使っているエディタなど好きな環境で作業できるのもありがたいです。いつも使っている検索コマンドをそのまま使えたりして、簡便だなと。これがもし、ヘルプ管理用のブラウザの画面などで一つひとつ直していく、という感じだったら、もっと大変だったかなと。
まとめ
履歴を管理したり、レビューをしたりというのは、ソースコードでは当たり前にやっていることだと思うのですが、同じような感じで、ヘルプでも運用してみたところ、とても良い体験を得られたのでオススメです。
この運用を始めた年明け以降、新たに追加するヘルプは全てこの運用に乗せて、編集を通しています。
既存のヘルプに関しては、日々のサポートの中で説明の仕方がどんどん改善されているので、それを反映するために全てのヘルプを頭から見直していくつもりで、それなりに時間がかかりそうですが、説明も文章も、今より一段レベルアップしていけるのではないかなと思っています。
余談ですが、編集者の仕事を間近で見るのは初めてなのですが、数百字程度の文章でも、日をおいて何周かチェックして、都度、細かい修正を入れている過程はとても勉強になるので、最終的な修正内容だけでなく、コミットごとの差分を追っていたりします。
