WebサービスのヘルプをGitとかで編集する
こちらは『書き手と編み手の Advent Calendar 2019』の2日目の記事です。
昨日はid:mohriさんの以下でした。
さて、続く私はWebサービスのヘルプを編集することについて書きます。
といっても、あんまり汎用的・抽象的な話ではなく（そうしたかったんですが、ならず）、やや特殊な事例かもしれません。あらかじめご承知おきのほど・・。
ぼくは昨年の11月にそれまでのフリーランス編集者（兼たまにライター）からIT企業の会社員に転職しまして、現在はその会社が開発・運営しているWebサービスのカスタマーサポート、兼編集者みたいなことをしています。
＊転職時のブログ記事はこちら。
ここで言うWebサービスとは以下で、
こちらは見積書や請求書などの取引で使う書類をクラウドで作成・管理したり、そこで登録した金額を使って売上分析・経営管理できるよ、みたいなものですが、これのチャットサポートをしながら、そのサービスに関わるヘルプ記事の校正・テキスト表現の監修みたいなことをしています。*1
このヘルプ、現在400本ぐらいありますが、
そのすべてを同サービスのメイン開発者であり弊社代表でもある田向さん（id:fw_tx76129）が書いていまして、何しろこのサービスは元々田向さんが自分が欲しくて作った（理想に合致するものがあれば使ったけど、なかったので作った）もので、コードも最初のプロトタイプから今に至るまでずっと中心になって書いているので、その仕様については誰よりも彼がよく知っていて、だからそういうこともできるわけですが、とはいえ同サービスがスタートしてからぼくが入社するまでの4年ちょっとの間、ヘルプの文章は他の誰も触っていない状態だったので、いわば「外部の目」によるチェックというのはほとんどされていない状態だったのですよね。
で、そこにぼくが入ってきたということで、じゃあ編集、やりましょうかやりましょうよ、ということで、まずは校正的な視点で表記を揃えたり、ちょっと内容が伝わりづらそうなところを適当に書き換えたり、ということからスタートしてできたのが以下のようなシステムでした。
詳しくは上記の田向さんによる記事をご覧頂きたいですが、簡単に解説すると特徴は2点で、
という感じです。
とくに大きいのは前者のバージョン管理で、以前はその1本目の記事にも解説されているとおり、HTMLエディタ形式の管理画面で編集してそのまま保存するような仕組みだったので、もし修正してもその差分（どこをどう修正したのか）はわからず、とくに複数人で編集する場合には困難が生じそうな状況でしたが、ここにGitをかませることで、第一に複数人による作業が非常にしやすくなり、また普段づかいのエディタ（Vim）でローカルのテキストファイルを気軽に編集できるようになり、感覚的には「コードを書くようにヘルプを書く（編集する）」みたいな感じになりました。
さらには、これによって上記2点目の特徴であるリントツールも経由できるようになり、事前に登録しておいた「辞書」と異なる表記をしていたらエラーが出るようになっています。
その作業の流れについて、もう少し具体的に書いてみると、こんな感じ。
- まず修正前のブランチを元に修正用のブランチをチェックアウト。
- その中でどんどん修正＆コミット。
- 時間がかかりそうだったら一旦途中でプッシュして、Draft Pull Request（WIPみたいなやつ）を作成。
- 1本の記事につき頭から終わりまでを2〜3周ぐらい読み直しながらつど修正。
- 終わったら、DPRからPRに切り替え。田向さんにアサインを移す。
ちなみに、Git操作はSourceTreeを使っています。
ぼくは以前は、Git操作なんて黒い画面でやってナンボでしょ、GUIなんて邪道！と思っていましたが、入社してみるとエンジニアで黒い画面を使っている人はいなくて（笑）むしろSourceTreeの割合が多かったので、あっさり改宗。
普段それを本業で使ってるエンジニアさんにGitやSourceTreeの使い方を教われるなんてありがたすぎるので大人しく教わった次第でしたが、なんやこれ、めっちゃ便利やん！という感じで今では手放せないものになっています。*2
上記を踏まえて、あらためてそれらツールに着目しながら手順を追うと、こんな感じ。
- SourceTreeでブランチ作成・チェックアウト。
- エディタでひたすら編集。コミット。
- 途中でプッシュ。GitHub上でDraft Pull Request。
- エディタで編集の続き。コミット。プッシュ。その繰り返し。
- GitHub上でPull Requestに切り替え。
実際は上記に加えて、Ruby製のMiddlemanを使ってプレビューを確認したり、
Middleman: 作業を効率化するフロントエンド開発ツール
Perl製の自作ツールを使って対象ファイルをシュッと開いたりしていますが*3、そこまで説明していると細かすぎて伝わらないアドベントカレンダーになってしまいそうなので*4、ここまでにしたいと思います。
本当はこの後、Webサービスのヘルプを編集するとはどういうことか、その時にはどんなことに気をつけて、何を考えているのか、みたいなことも書きたかったのですが、ここまでの話でちょうどキリが良い感じがするので、その辺はまた日にちが空いていたら書くかも、という感じにしておきます。
本日の記事は以上です。ひき続き、『書き手と編み手の Advent Calendar 2019』をお楽しみください！
*1:チャットサポートをどんなふうにしているのか、という話はたまたま先月初頭に行われたテキストエディタVimの国際カンファレンス VimConf 2019 にて簡単なLT（登壇）をしましたので、ご興味おありの方はぜひどうぞ。 docs.google.com www.youtube.com
*2:まあ、黒い画面と格闘した日々があったからこその感動なのだとは思いたいですが。
*3:これについてはコレの最後の方で紹介しています。 note103.hateblo.jp
*4:もう遅いかも。
