Hatena::ブログ(Diary)

naoyaのはてなダイアリー

January 27, 2014

Github を使って雑誌原稿を書く

今日はこのあと Github の Tokyo Drinkup January 2014 に行くのだが、先方から、もしかしたら 10分ほど Github について話してもらうかも、と打診された。話すか話さないかわからないが、もし話すとしたらと仮定し内容の整理も兼ねて以下「Github を使って雑誌原稿を書く」ということについて書いてみようと思う。

「Github を使って雑誌原稿を書く」もしくは「Github を使った雑誌編集者とのコラボレーション」について、である。

Web+DB PRESS の連載

ご存知の方もいるかもしれないが、このところ技術評論社の Web+DB PRESS で連載をしている。連載を始めて、もう一年近く経った。以前にも Perl に関する連載をしていて、そのときも数年ぐらい続けたので、間があきつつも、なんだかんだでそれぐらいの付き合いになる。

最近は特にテーマは決めずに、隔月ごとに、そのとき旬な物あるいは自分が強く興味がもっていることについて書いている。RubyMotion の話を書いたかと思えば、serverspec の話を書いたりとかそんな感じ。もし良かったら読んでみて下さい。宣伝終わり。

Github 以前

数年前の当時、まだ Github が世の中にリリースされるかされないか、その頃の雑誌原稿のやりとりは基本メールだった。連載〆切りが近づいてくると、編集者さんから「そろそろいかがですか」的なメールがきて、あとはそのメールをピンポンしながらやりとりをする。原稿も適当なフォーマット (当時ははてな記法)で書いて、メールに添付して送る。

しばらく待っていると、原稿が PDF になるなり何なりして、そこから校正作業が始まりなんどかやり取りしたところで完了となる。

まあ、特にこれで何か特段困ったことがあったかというと実はそういうことはなかった。

当然、原稿そのものは手元で Subversion、その後 Git でバージョン管理はしていたし、Github を使うようになった今でもコミュニケーションのピンポンを繰り返してやりとりしていって校了となる・・・というフローそのものは変わっていない。

Github 以降

このメール時代の頃から原稿を Git で管理することはしていたけれど、それはローカルだけの話でリモートに push したりはしていなかった。

それを、今回の連載を開始するにあたり、そろそろ Github もコモディティになってきたことだしということで、担当の @inao さんに github に push するからそこでコミュニケーションしてみませんか、と提案した。ただ、このときは特に深い狙いはなく、どうせ手元でバージョン管理してるんだからリモートに上げるのもすぐだし、メールに添付するよりはそっちのほうが共有が楽とかそのぐらいしか考えてなかった。

それが、Github を使い始めてから作業のやり方に色々とアイデアが出てきて、今では原稿は Markdown で書き、お互い基本的に Pull Request で飛ばす方法が定着した。Pull Request はいわゆる「Working In Progress」な WIP Pull Request として出す。つまり、原稿を書き上げたところで Pull Reuqest するのではなくて、いきなり Pull Request を出してしまってあとはその Pull Request に、原稿の進捗に合わせてコミットを重ねていく。

このブログで再三にわたって紹介しているが、WIP Pull Request については

このスライドが分かりやすいと思う。

Pull Request で原稿をやりとりする

以下がその WIP Pull Request の様子。簡単な TODO を共有し、少しずつ原稿を追加していっている様子が伝わると思う。編集者は「naoyaさん原稿書いてますか?」とかメールを送ってこなくても、進捗が把握できる。途中でレビューを加えようと思えばいつでもそれは可能だ。

f:id:naoya:20140127180235p:image:w640

原稿をやりとりするフローでは、最初は著者側にボールがあって、PDF化の作業なんかが始まるとボールは編集側に移る。PDFを確認するタイミングになると著者側にボールが移る。その繰り返しである。そして、自分と @inao とのやりとりでは、Pull Request を出した側がそのボールを持っているという関係になっている。

例えば、ぼちぼち著者の手元での原稿が固まってきたな・・・という頃に @inao がその Pull Request をメインブランチにマージする。マージした段階で「あ、向こうにボールが渡ったな」というのが分かるのでこちらはレビュワー側に回る。

以下はその、編集側から飛ばしている Pull Request。

f:id:naoya:20140127180420p:image:w640

コミットログを綺麗に整理してくれているので、こちらも、自分の原稿にどんな修正が入ったかがよくわかる。ああ、結構 typo 編集してくれてるんだなとか、用語統一とか、読みづらいところを校正してくれてるんだなとか。今だから言えるが、以前メールで作業していたときは、こういう細かい所まで作業してもらっているということにあまり気づいていなかった。

Git をお互いに使っている、という利点が活きる場面も結構多い。

例えば現在の原稿はちょっと書きすぎてしまってページ数がその分確保できるか怪しいという話があって内容を少し削ったのだが、仮にページ数を確保できた場合には元に戻そうという話をしていて、実際確保できそうだったので削除コミット自体を revert して元に戻す、なんてことをした。メールでやりとりしていたときは、こういうコラボレーションはなかなか難しかった。

f:id:naoya:20140127181332p:image:w640

このように、Github + Pull Request の利点を上手く活かして編集とやりとりすることができている。

自分たちはそこまでやっていないが、知人のエンジニアは、Jenkins を回して git push の度に PDF のビルドとか用語統一とかそういうのを自動化しているなんて話もしていて面白かった。

わかったこと

メールでやりとりしていたときにも、そこまで困ったことはなかったけれども、Github にしてからはずいぶんとやりやすくなった。

Pull Request による進捗とコミュニケーションの一本化

色々と良かったところはあるのだけれど、ざっくりいうとそれはお互いの作業状況が見えること、そしてその作業状況にコミュニケーションがうまく集約されることとだと思う。

Pull Request ベースの開発をしたことがある人ならよくわかると思うが、Pull Request は単にパッチを取り込んでもらう依頼が簡単になるということだけでなく、その Pull Request のスレッド上でコミュニケーションを重ねることで、作業進捗とコミュニケーションが一つにまとまった形で可視化されるところがすごく良い。大袈裟にいえばワークフローとコミュニケーションの一体化、とも言える。

雑誌原稿の執筆作業のワークフロー自体は、関連する人間は2人から3人程度だしシンプルなのだけれども、その昔メールでピンポンしていたやり取りが原稿の commit や typo の修正といった一つ一つの作業と関連づけられる形でスレッドになるのは、後日見返したときにすごく安心感がある。どちらが作業のボールを持っているかも明確になるし、数日おいて原稿の状況を確認するにあたって「どんな議論になってたっけかな・・・」というのを思い出すのも Pull Request の状況を見るだけでほとんどストレスなく思い出すことができる。

元々 Github を使い始めた当初は Pull Request ではなく、Issue で原稿の進捗を管理していた。@inao から、〆切り日にあわせてこの日までにアウトラインが欲しいとか、これこれを終わらせてくださいとか、その単位で Issue を切っていた。でも、実際には個別の Issue にするほどそれぞれの作業は独立していなくて、基本原稿書きは逐次で物事が進んでいくので、WIP な Pull Request に一本化してその上でやりとりしていくほうが面倒もすくなく、且つ分かりやすかった。

こうして作業が可視化され、ストレスなく状況を把握しやすくなったことによって、著者と編集者の間でのちょっとした行き違いみたいなことがだいぶ少なくなった。結果的に「ああ、こんなに自分の誤字脱字を編集してくれてるんだな」とか今まであまり気づいていなかった作業についても自覚することができるようになり、より良い信頼関係を築くに至っている・・・と @inao は知らないけど、自分は思っている。

Github がソフトウェア開発以外で活きてくる可能性

そんなわけで、Github はソフトウェア開発の分野以外にも、コラボレーションが必要な領域で色々と応用の可能性を持っている、と自分は思っている。

実際、昨年 Github が資金調達をした際に今後はいろいろな分野に Github を広げていくみたいな話をしていたように記憶しているので、そういう利用シーンもこれから増えていくのではないかと思っている。雑誌の原稿編集だけでなく、自分でも気づいてない分野の応用例なんかがでてくることをとても期待している。

問題は、@inao のように Git と Github を使いこなせる編集者が世の中にほとんどいない、という点ではないかという話があるのだがそれについては今は考えないでおくとしよう。