2019』の2日目の記事です。adventar.org昨日はid:mohriさんの以下でした。mohritaroh.hateblo.jpさて、続く私はWebサービスのヘルプを編集することについて書きます。いっても、あんまり汎用的・抽象的な話ではなく(そうしたかったんですが、ならず)、やや特殊な事例かもしれません。ご承知おきのほど・・。ぼくは昨年の11月にそれまでのフリーランス編集者(兼たまにライター)からIT企業の会社員に転職しまして、現在はその会社が開発・運営しているWebサービスのカスタマーサポート、兼編集者みたいなことをしています。*転職時のブログ記事はこちら。できるよ、みたいなものですが、これのチャットサポートをしながら、そのサービスに関わるヘルプ記事の校正・テキスト表現の監修みたいなことをしています。boardそのすべてを同サービスのメイン開発者であり弊社代表でもある田向さん(id:fw_tx76129)が書いていまして、何しろこのサービスは元々田向さんが自分が欲しくて作った(理想に合致するものがあれば使ったけど、なかったので作った)もので、コードも最初のプロトタイプから今に至るまでずっと中心になって書いているので、その仕様については誰よりも彼がよく知っていて、だからそういうこともできるわけですが、とはいえ同サービスがスタートしてからぼくが入社するまでの4年ちょっとの間、ヘルプの文章は他の誰も触っていない状態だったので、いわば「外部の目」によるチェックというのはほとんどされていない状態だったのですよね。そこにぼくが入ってきたということで、じゃあ編集、やりましょうかやりましょうよ、ということで、まずは校正的な視点で表記を揃えたり、ちょっと内容が伝わりづらそうなところを適当に書き換えたり、ということからスタートしてできたのが以下のようなシステムでした。tamukai.blog.velc.jptamukai.blog.velc.jp詳しくは上記の田向さんによる記事をご覧頂きたいですが、簡単に解説すると特徴は2点で、Git/GitHubを使ってヘルプ記事をバージョン管理するtextlintを使って表記揺れを自動的にチェックするという感じです。大きいのは前者のバージョン管理で、以前はその1本目の記事にも解説されているとおり、HTMLエディタ形式の管理画面で編集してそのまま保存するような仕組みだったので、もし修正してもその差分(どこをどう修正したのか)はわからず、とくに複数人で編集する場合には困難が生じそうな状況でしたが、ここにGitをかませることで、第一に複数人による作業が非常にしやすくなり、また普段づかいのエディタ(Vim)でローカルのテキストファイルを気軽に編集できるようになり、感覚的には「コードを書くようにヘルプを書く(編集する)」みたいな感じになりました。これによって上記2点目の特徴であるリントツールも経由できるようになり、事前に登録しておいた「辞書」と異なる表記をしていたらエラーが出るようになっています。textlint.github.ioその作業の流れについて、もう少し具体的に書いてみると、こんな感じ。修正前のブランチを元に修正用のブランチをチェックアウト。その中でどんどん修正&コミット。Request(WIPみたいなやつ)を作成。1本の記事につき頭から終わりまでを2〜3周ぐらい読み直しながらつど修正。終わったら、DPRからPRに切り替え。田向さんにアサインを移す。ちなみに、Git操作はSourceTreeを使っています。www.sourcetreeapp.comぼくは以前は、Git操作なんて黒い画面でやってナンボでしょ、GUIなんて邪道!と思っていましたが、入社してみるとエンジニアで黒い画面を使っている人はいなくて(笑)むしろSourceTreeの割合が多かったので、あっさり改宗。普段それを本業で使ってるエンジニアさんにGitやSourceTreeの使い方を教われるなんてありがたすぎるので大人しく教わった次第でしたが、なんやこれ、めっちゃ便利やん!という感じで今では手放せないものになっています。*2上記を踏まえて、あらためてそれらツールに着目しながら手順を追うと、こんな感じ。SourceTreeでブランチ作成・チェックアウト。エディタでひたすら編集。