Pro Git第2版の驚くべき冒険と最終的なツールチェーン

ほぼ6年前、私はApressから執筆が予定より遅れていたPro Gitと呼ばれる本の手伝いの誘いを受けました。結局原著者が書き続けないことを決めて、私が最初から書き直して2009年8月頃に最終的に出版されました。最初の3章あたりは、私はWordで本を書きました。そして編集者に文書を送って、しばらくして最終的な版を手にしました。

この3章のあとで、私たちが執筆と技術的な編集段階のためにMarkdownに切り替えて、同意された編集のためにだけWordへ戻るように提案したとき、私はやめようとしていました。一旦本が完成したら、私はすべての内容をMarkdownへ再び戻したので、それを私が作成したWebサイトにおいてオンラインで発表できました。幸運にも、原著者は著作をクリエイティブ・コモンズ・ライセンスとすることでApressと同意しました。

1年以上あとで、本が公開されるとすぐに人々がオープンソースの内容からKindleとほぼ互換の版を作り出しましたが、ApressもKindle版をリリースしました。

Pro Git第2版

本はまあまあ良かったので、印刷されておよそ4年後に、Apressは新たな版を書くよう私に持ち掛けてきました。その間に、私の会社のGitHubは数千人のユーザのためのサイトに取り組む4名の状態から、無数のリポジトリをホスティングして200名以上を雇用している巨大なオンラインの存在に成長しました。GitHubコミュニティが大きく変わっただけでなく、ツール自体にも重要な変化がありました。私は恐らく内容を改訂するときだと認めました。

皆さんは現在第2版（ならびに第1版）を オンライン で読んだり、お気に入りの端末で読むためにPDF・ePub・Mobi（Kindle）フォーマットでダウンロードできますが、この版がおよそ5年前の初版から作り出された方法の変化は、共有するのに面白い話ではないかと思いました。

Pro Git第2版の執筆

実際には過去数年間で数回Pro Gitを改訂していました。大部分はそのツールチェーンの面に興味を持っていました。Pro Gitを書くために”使いたかった”ツールチェーンの種類を示す Git Scribe と呼ばれるプロジェクトを、私はある時点で始めました。Scribeツールは、特別にフォーマットされたAsciidocの文書を用いて、良好なHTML・PDF・ePubとMobiの電子書籍を生成するツールチェーンをインストールするための、いくらか簡単な方法を提供しました。そのプロジェクトが終了して、結局私たちは代わりにO’ReillyのAtlasプラットホームを使うことになりましたが、Scribeプロジェクトは私をまず最初にAsciidocへ導きました。

Asciidoc

そこで私はPro Gitの大部分をAsciidocに切り替えました。Markdownによる問題はあまりに単純だったという点でした。表のフォーマット、相互参照、索引、付記、ソースコード例などを指定できませんでした。Asciidocがフォーマットで行うことのすべては単に書くことが簡単なだけでした。

私がMarkdownからすべてをAsciidocへ移すと、一部の出版者が同様にしていると気づきました。簡単にDocbookを生成できる点からO’Reillyが本をAsciidocで書くことを認め始めました。また実用主義のプログラマはそれ以前にしばらくの間単純なマークアップ言語を使っていたと思います。

ここで最も重要なのはAsciidoctorの立ち上がりでした。Git Webサイト（git-scm.com）を作り直したとき、私はGitのためにAsciidocのmanページを取得してちゃんとしたオンライン版を作りたいと思っていました。またそれをRubyでやりたいと思っていました。私の友人とGitHubの協力者Nick Hengeveldは、Asciidocがそうする手助けとなる良いパーサとフォーマッタを書きました。結局他のGitHubber（Ryan WaldronとJeremy McAnally）が加わって、Asciidoc.rbをAsciidoctorに変えました。そして驚くべきDan Allenが最終的に引き継いで、プロジェクトを全く新しいレベルへ引き上げました。

Asciidoctorがそばにある現在、以前ほど単純ではなくなったAsciidocソースの本を使って、本当に驚くべきことができます。

GitHub

執筆のワークフローで最も大きな変化の1つは、GitHubが以前よりもっと良くなっている点でした。レビューとコメントのためのプルリクエスト、章の計画のためのIssueマイルストーン、より簡単なレビューと抜き取り検査のためのProseの差分、執筆とAsciidocプレビューのためのAtomテキストエディタがすでにありました。

私たちが使うワークフローだと、これまでに技術書を、特に共著者と書いている人なら誰でも、恐らく嫉妬で気が変になるでしょう。

私たちは望むすべてを書き出して、各章のマイルストーンに紐付けられるissueとして主要な点をすべて加えて、何をするつもりか各々決めて、書き始めました。私たちは作業の単位（通常は章）のためにブランチを作って、執筆とGitHubブランチへのプッシュを始めることができました。私たちの一人が変更をプッシュしたときは常に、私たちはSlackで話してすぐに最新版を得ました。通常はマージ前に終えたかったことのチェックリストによって、私たちはほとんどすぐにプルリクエストをオープンしたので、各ブランチの状態が何であるかを見分けられました（ 例 ）。

ブランチが長く続いたとき、私たちはそれを最新にしておくためにマスターブランチをマージできました。また章を複数のファイルに分けるような大きく構造的な変化であっても、衝突が決して大きな問題ではない点を確認できました。

レビューはプルリクエストによって行われました。私たちは取り入れられたテキストのどの行にもコメントを残して、それについてその場やチャットで会話できました。

Asciidoc Atom プレビュープラグインをインストールして、私が書いていたテキストのライブビューを書いていたとおりに得られました。また追加・修正・削除されたことやどのブランチにいるかについてのサイドバーのヒント、マージの衝突を解決するツール、Zenモードなどを含んでいました。驚くべき執筆環境でした。

しかしこれだけでなく、9つのタイムゾーンに分かれて協働のほとんどを行いました。また私たちの編集者は本の進捗を知るためにマイルストーンのページをいつでも見ることができました。

皆さんがモダンなGitHub上のAsciidocを使わなけれず技術書を書いたとしたら、それは必要より10倍多く作業したことになるでしょう。

Atlas

第2版の方法だと執筆と協働が第1版より簡単なだけでなく、無限に簡単なことのように思われました。

O’Reilly Atlasビルドシステム。美しい電子書籍が数分のポイント＆クリックで。

数年前O’Reilly MediaでTim O’Reilly、Laura Baldwinや他の人とこのツールチェーンがどのくらいよくなるか会話したおかげもあって、彼らがより簡単にするために開発していたプラットフォームを試用するよう誘われました。Asciidocで執筆してからPDFへ「git push」することがいかにすばらしいかについて、私たちは同意しました。結局彼らはそれを実際に作ることになり、そしてありがたいことに、私はそれを試用できました。

数か月間私が 彼らのフォーラムでかなり活発 なのが分かります。そして私が何かに言及するたびに、彼らは数日あるいは数時間のうちに修正していました。しかもそのビルドは、私がAsciidocソースで注を作成して変更する間に、PDFを生成して、ダウンロードして、プレビューで読むことになる、章のレビューのための美しい出力を生成しました。

幸運にも、彼らにはサービスのためのAPIもあり、異なるブランチを別に構築できます。これはPro Gitリポジトリでpost-receiveフックをリッスンして、変更をプルダウンして、Atlasへプッシュして、自動的にビルドを始めるサービスを私が書けたことを意味します。それからすべてのビルドが終了するとポーリングして、私自身のAWS S3バケットへ動かして、新しいprogit.org Webサイトとgit-scm.com Webサイトの内容とリンクを更新します。

しかしそれだけでなく、Pro Gitが翻訳される”各言語ごと”にそうすることができます。これは近い将来、あなたが Pro Git Webサイトか git-scm.com Webサイトに行けば、最後の正誤表をマージしたあと、数分でPro Gitの最新版のどのフォーマットでもプロ級の電子書籍をダウンロードできることを意味します。どんな言語であっても。「マージ」ボタンを押したあと、著者や言語メインテナからの作業”ゼロ”で。

今や基本的にこの惑星で最も単純で最も洗練された多言語電子書籍の製作と販売の仕組みがあります。

オープンソース

第1版と第2版のもう一つの興味深い違いは、私が完全に本を書いて、Wordに変換して編集するApressに「丸投げ」して、私たちに変更を送ることに、私たちが同意したという点です。というのも私がMarkdownの過程を維持した上でMarkdownを経てWordへ再び進みたくなかったためです。これは私が以前できたよりもかなり早い段階で、Benと私が本をオープンソースにできることを意味します。

この本は現在すべての電子書籍フォーマットを含めて オンラインで完全に入手できます が、恐らく数か月はまだ印刷されないでしょう。この間に私たちがたくさんの小さな編集と技術的な訂正（すでに最初の24時間でいくつか訂正しました）をすることは確実であり、Apressが印刷する前にそれらをマージできます。これは私たちが本を実際に印刷する前に誤りを見つけて直せることを意味します。これはかなり素晴らしいです。

私たちが再びオープンにする前に、本の全てをオープンで書くか、ほとんど出来上がるまで待つか、実際に議論しました。結局私たちは後者を選びました。とはいえ前者がより良い選択肢でなかったと私はまだ確信していませんが。全過程で全コミュニティからの意見に対処することはあまりにも大変で、基本的にもう少し内容を所有していたいと私たちは感じました。しかし他のルートへ進むと興味深くなるかもしれません。恐らく次の場合です。

翻訳

この場合で最終的に著しく異なるのは著作物の翻訳を取り扱う点です。第1版をオープンソースにするとき、私は翻訳について考えていたか全く覚えていません。私は最初に翻訳された仕事を覚えていませんが、リリース直後にすべてを「en」ディレクトリへ置くためにディレクトリを再構成したので、リリース後にかなりすぐに翻訳される必要がありました。

本が出版された5年間に、完全には少なくとも10の言語（ドイツ語、簡体字中国語、繁体字中国語、フランス語、日本語、オランダ語、ロシア語、朝鮮語、ポルトガル語、チェコ語）へ翻訳されて、部分には恐らく他の20の言語に翻訳されました。私がそれらを主なリポジトリのサブディレクトリで保存すると決めて、それらのためのプルリクエストを受け入れました。これはリポジトリへの書き込み権限を持つ誰かがそれらをマージする必要があることを意味しました。そしてたとえ私がそれらの言語をほぼ何も読めなくても、基本的には私がすべてをマージする必要があることを意味しました。結局数年後に私はプルリクエストについていくのがかなり難しくなり、そして驚くべき Jean-Noël Avila が引き継いで、以来ずっと翻訳（英語の正誤表さえ）を管理しています。

しかし今回私たちは以前の問題から学んで、誰にとってもより簡単にしようと試みることができます。今回は、我々はあらゆる翻訳をprogit organization配下の別々のリポジトリに作っていて、言語に特有のメインテナーをそれぞれ加えています。これは皆さんが標準中国語のZH版でIssueをオープンできて、全く混乱させないことを意味します。もしメインテナーが応答しなくなって他の誰かが興味を持っているなら、私たちは新しいメインテナとして彼らを加えられます。

Atlasのおかげで、これまでの場合がそうだったように、全員に彼ら自身のビルドをローカルで実行させる代わりに、各翻訳はそれ自身の自動化されたビルドの過程も備えます。

まとめ

以上の過程が少なくとも技術的な出版の中期的な将来への近道だと、私は信じています。GitHub上のAsciidocのように、皆さんの本を簡単なフォーマットで書くと、皆さんの編集者や共著者と容易に協働できます。またAsciidocやAtlasのようなツールを使うと、その内容をオープンソースにして、堅牢な翻訳コミュニティを受け入れて、自分自身で出版することができます。

この全てには出版業界全体にとってとても深刻で興味深い意味があるとも、私は信じています。それについて今後の投稿で詳しく書くつもりです。