テクニカルライティングの未来を先取り ー Asciidoc フォーマットと GitHub を使って技術書 Pro Git を共同執筆
Pro Git 第2版の「最高の執筆過程」と「最終的な制作環境」
ちょうど6年ほど前、出版社の Apress から「執筆スケジュールが押している本を手伝って欲しい」と連絡があった。本のタイトルは Pro Git。ほどなくして元々の著者が執筆を断念することになり、僕が一から書きなおして2009年の8月ごろに出版にこぎつけた。最初の3章分くらいは Word で書いていて、書き上げたファイルを編集者に送り、しばらくすると訂正版が送り返されてくる、といった感じだった。
でも、このやりとりを3章分も続けているといよいようんざりしてきたので、「Markdown フォーマットを使わないか」と頼んでみた。執筆と技術的内容の訂正は Markdown で、その後の出版に向けた校正については Word で、というお願いで、編集者からの合意も得られた。本が完成したあとには、文章をすべて Markdown に戻しておいた。用意したウェブサイトで公開しやすくするためだ。さいわい、執筆した文章にクリエイティブ・コモンズ・ライセンスを適用することについては、元々の著者が Apress から了承をもらってくれていた。
出版から約一年以上たった後、本の Kindle 版を Apress が出した。とはいえ、紙の本が出版された直後から、オープンソースで公開された本のデータを使って Kindle 用のデータがあちこちですでに生成されていた。
Pro Git 第2版
この本はそれなりに良く売れていたようで、出版から4年後、「第2版を書かないか」と Apress から依頼を受けた。その4年の間に、僕の勤め先である GitHub は数千名のユーザーが使うサイトを作ってる4名の会社から、従業員数200名以上、ホストするリポジトリは数百万という会社に成長していて、ネット上の存在感も巨大になっていた。GitHub のコミュニティは大きく成長したし、GitHub というツールそのものもずいぶんと変わってきていた。そんなわけで、本の内容を見直すにはちょうどいい時期では？、という提案を受けることにした。
なお、第2版はもうネット上で読めるようになっていて、好みのデバイスで読めるように PDF・ePub・Mobi（Kindle）形式でダウンロードできるようにもなっている。いずれも第1版でも出来ていたことなのだけど、製作工程5年前と今回で変わった。興味をもつ方もいるかと思うので、その違いを説明してみようと思う。
Pro Git v2 の執筆
これまでに、Pro Git の改訂は何度か手をつけていた。変えたいと思っていたのは主に制作環境の部分で、それが Git Scribe というプロジェクトを始めるきっかけになった。Pro Git を書くときにこんな制作環境があればよかったのに、という思いを形にするためのプロジェクトで、Asciidoc フォーマットで書かれた文章をいい感じの HTML・PDF・ePub・Mobi に変換してくれる制作環境が簡単に用意できるようになる予定だった。このプロジェクトはうまくいかなくて、結局は O’Reilly の Atlas を使うことになったけれど、このおかげで Asciidoc の良さを知ることはできた。
Asciidoc
そういったこともあり、Pro Git の大半は Asciidoc で書き換えてあった。仕様がシンプルな Markdown では、表の書式・相互参照・索引・付記・ソースコード表記などをうまく記述できなかったからだ。Asciidoc を使えば、Markdown と同じくらい簡単に記述できた。
Pro Git の書式を Markdown から Asciidoc に移行したあとで、同じように移行した出版社があることに気づいた。Docbook データの生成が容易だったので、O’Reilly は Asciidoc で書かれた原稿を受け付けはじめていたし、Pragmatic Programmers では以前から独自のマークアップが使われていたと思う。
こういった状況のなかで、Asciidoctor というツールが出てきたのはとても大きかった。Git のウェブサイト (git-scm.com) を作りなおすときに、Ruby を使って Git の man page のソース（Asciidoc で書かれている）をウェブサイト用に変換したいと思っていたところ、友達で GitHub の同僚でもある Nick Hengeveld がそれに使えるパーサーを書いてくれた。その後、Nick 以外の同僚たち (Ryan Waldron と Jeremy McAnally) も加わってくれて、Asciidoc.rb というパーサーをもとに Asciidoctor が生まれた。それを、あの Dan Allen が引き継いでくれて、Asciidoctor は生まれ変わることになった。
Pro Git の原稿で使った Asciidoc はかなり複雑になってしまったけれど、いまの形になった Asciidoctor のおかげでいろんな加工ができるようになっている。
GitHub
執筆手順に関して第1版と第2版で大きく変わった点といえば、GitHub がずっと使いやすくなったことだと思う。プルリクエストを使ってレビューができるようになったし、Issue のマイルストーンを使えば章ごとの計画も立てられるようになった。文章用の diff を使って変更箇所を簡単にチェックできるようになったし、テキストエディタの Atom を使えば執筆しながら Asciidoc のプレビューもできた。
第2版の執筆手順は、技術書を書いたことがある人、特に技術書を共著で書いたことがある人なら誰もがすごく欲しがるものだと思う。
実際の流れはこうだ。まず、第2版でやりたいことを全て書き出して、重要な点を issue として登録した。次に章ごとにマイルストーンを作って issue を割り振ったら、取り組む issue を各自が決めてから実際の文章を書き始めた。取り組もうとしている作業用にブランチを切っては（章ごとに切った）、ときどき GitHub にプッシュした。話し合いが必要なときは Slack を使った。どちらかが何かをプッシュすれば、すぐに Slack から通知が届くようになっていた。WIP のプルリクエストを作って、マージまでの TODO リストを書いておくようにした。これのおかげで、ブランチの状態がわかるようになった（例）。
作業中のブランチがマージまでに時間がかかるようなら、ときおり master ブランチをマージして最新化するようにした。そうしておけば、大規模な構成変更（章を複数ファイルに分割するなど）を行ってもコンフリクトで悩まずに済むからだ。
レビューにはプルリクエストを使った。追加された行に気になった点をコメントしたり、チャットで話しあったりもした。
Atom テキストエディタに Asciidoc Atom preview プラグインを導入して、執筆途中のテキストを常に変換した状態でプレビューできるようにもした。追加・変更・削除の有無をサイドバーに表示したり、どのブランチにいるかわかるようにしたり、マージのコンフリクトを解消するツールや zen モードなんかも使った。とにかく最高の執筆環境だった。
ここまでの内容だけでもすごいことだけど、僕らはそれをタイムゾーンが9つも離れた状態でやってのけた。しかも、担当編集者はマイルストーンのページを見れば進捗をいつでも確認できるようにもなっていた。
技術書の執筆にまつわるこれらすべての作業を Asciidoc や最新の GitHub を使わずに行っていたら、作業量は10倍になっていたかもしれない。
Atlas
実際の共同執筆作業は第1版のときよりずいぶん簡単になったけど、第2版では仕上がりを確認するのもずっと簡単になった。
数年前、こういった制作環境はいくらでも改善の余地があるよね、という話を、Tim O’Reilly、Laura Baldwin や O’Reilly Media のみんなとしたことがあった。そのかいあってか、それを実現するために彼らが開発中のツールを、試してみるよう声をかけてもらえた。「Asciidoc で書いて ‘git push’すると PDF が生成されたら最高だよね」なんて話をしていたら、実際にそれができあがって、試させてもらえることになったわけだ。
Atlas の掲示板を見れば、数か月にわたって僕が積極的に書き込んでいたのがわかると思う。何か書き込めば、数日、ときには数時間のうちに直してくれていた。さらに、実際に出力されるデータはとても良く出来ていた。あまりにも読みやすかったので、章を通してのレビューをするときは Atlas の PDF をダウンロードしてきて、プレビュー.app で読みつつメモを取りながら Asciidoc のソースを修正していたくらいだ。
さらにありがたいことに、Atlas には API も用意されていたし、ブランチごとにビルドを走らせることもできるようになっていた。それはつまり、Pro Git リポジトリの post-receive フックを使って、変更点を Atlas にプッシュしてビルドを自動実行させることもできるということだ。実際にそういうツールを書いて、自動ビルドされたデータの AWS S3 のバケットへの転送や、progit.org と git-scm.com のリンクやコンテンツの更新を自動化した。
しかも、この自動化は Pro Git の翻訳版すべてに流用できるようになっている。Pro Git や git-scm.com のサイトにアクセスすれば、いつでもプロ仕様の電子書籍が各種フォーマットでダウンロードできるようになる、ということだ。しかも、直近の誤字修正まで取り込んだ最新のバージョンを、すべての言語で、だ。僕や各翻訳版のメンテナーは、‘merge’ ボタンを押すだけでいい。
これは、この世に存在するもっとも簡潔かつ高機能で、多言語に対応した電子書籍制作・配信の仕組みだと思っている。
Open Source
もう1点、第1版と第2版の違いで大きかったのは、本を書き上げたらあとは Apress に「ポイッと丸投げ」してもいい、という点で合意できたことだ。Markdown から Word に、そのあとまた Markdown に……というのはもうやりたくなかったからね。このおかげで、Apress のほうで Word に変換して出版に向けた校正をしてくれるようになり、結果だけがこちらに知らされるようになった。また、こうしたことで、原稿を第1版よりずっと早くオープンソース化することもできた。
この本は現時点で、電子書籍データも含めすべてネット上に公開されている。けれど、紙の本として出版されるまでにはしばらくかかると思う。その間に、きっと細かい修正（文言や技術的内容）が山ほど届くはずだ（最初の24時間ですでにいくつか届いている）。そして、Apress が印刷に回す前には集まった修正をマージできるだろう。誤りの修正を出版前に行えるわけで、これってほんとにすごいことだと思う。
本の内容をいつネット上に公開するかについては、始めからそうすべきか、それともほぼ完成した段階まで待つべきか話し合った。結局のところ後者に落ち着いたわけだけど、前者のほうが良かったかもしれない、と今でも思ったりする。公開の時期を決めたときは、作業の全過程においてコミュニティからのフィードバックを受け続けるのは負荷が高すぎると感じていた。書いた内容を、少しの間は出さずに取っておきたいという気持ちもあった。ただ、ひょっとすると前者の方がおもしろくなったかもしれない（次回はそうするかも）。
Translations
最後に、翻訳の取り扱いが大きく変わったことについても触れておく。第1版をオープンソースにして公開したときには、翻訳のことなんてまったく頭になかったと思う。翻訳された文章を初めてもらったのがいつだったか正確には覚えていないけど、原文を公開してからすぐだったはずだ。公開後ほどなくして、新たに ‘en’ディレクトリを作って原文データを全部そこに移動させてたから。
第1版が出てからの5年で、翻訳が仕上がった言語は少なくとも10ある（Deutsch, 简体中文, 正體中文, Français, 日本語, Nederlands, Русский, 한국어, Português and Čeština）。作業中の言語はさらに20ほど。当時、翻訳データを格納するために Pro Git のリポジトリに言語ごとのサブディレクトリを作ることにし、実際にプルリクエストも受け付けた。それはつまり、リポジトリの書き込み権限がある誰かがマージしなきゃいけない、ということだ。ここでいう誰か＝僕、なわけで、読める外国語はほぼゼロなのにも関わらず、マージ作業をすることになった。数年もするとプルリクエストをほとんど処理できないようになってしまったので、Jean-Noël Avila に引き継いでもらった。それ以来、彼が翻訳の管理（なんと原文の修正まで！）を一手に引き受けてくれている。
そこで、今回は過去の教訓から学び、みんなの負担を減らそうと思った。第2版では、GitHub 上の progit organization 配下に言語ごとのリポジトリを作り、各リポジトリにメンテナーを指名することにした。これで、中国語版についての issue をマンダリン（訳注：中国公用語の欧米での通称）で立ててもらえるし、こちらも混乱しなくて済むようになる。メンテナーのレスポンスが悪くなったら、他に興味のある人をメンテナーとして追加できるようにもなった。
また、Atlas のおかげで、自動ビルドの対象に翻訳も含められることになった。これで、今までのように各自が手元でビルドする必要はなくなる。
まとめに代えて
ここに書いた過程は、技術書出版における近い将来の姿、あるいはしばらく先の姿と言っても相違ないと強く思っている。具体的には、Asciidoc のような書きやすいフォーマットと GitHub を使って執筆を進めること、編集者や共著者との共同作業が簡単になること、本の内容をオープンソースにして公開すること、頼もしい翻訳コミュニティを取り込むこと、Asciidoc や Atlas のようなツールを使って自己出版すること、などが挙げられる。
また、こういったことの一つ一つが、出版業界そのものに与える影響は大きく興味深いものになる、と強く思ってもいる。これについては、今後の投稿で掘り下げることにしよう。
