私はこれまでIT技術についての書籍を十冊以上書いてきました。一般書店に並ぶものから同人誌まで、何百ページのものから数十ページくらいのものまで、さまさまです。
これらの本の原稿はすべてGitHubで管理してきました。本記事は私が長年蓄積してきたGitHubでの書籍の原稿管理方法を共有します。何事も直感に従ってその場のノリで動くという私の性格を強く反映したやり方なので、人によって合う合わないはあると思います。
私は文書の変更はかなり細かくコミットしていきます。筆が進むうちに書いたところまでコミット、ある程度時間が経てばコミット、です。コードとは違ってコミットを論理的な単位で分割しません。ごちゃごちゃ考えていると執筆の神様は逃げてしまうので、書いたらとりあえず永続化します。また、頻繁にコミットしてると進んだ感が出てきて滅入りにくくなるというメリットもあります。
コミットメッセージはほとんど書きません。主な理由は、コードと違って「過去にどのような契機でこの部分を変更したのかを正確に知りたい」ということがあまり無いからです。それなのにコードと同じ感覚で原稿を書こうとしても、いつまでたっても進みませんし、そのうち嫌になってきてやめてしまいそうなのでいいことが無いと考えています。
まとまった変更のためにbranchを切るようなことはしません。とくに、関係者に共有する前はPRなんて作らずに、どんどんmainにマージしていきます。例えば章ごとにbranchを分ける…というようなことをしても特にメリットは無いです。作っても後で忘れますし、思い出したときにはconflictだらけになっていたり、すでに不要な文書になっていることが多くてつらいです。そうではなく、思いついたら本文にすぐ反映させ、常に文書全体の構造を頭に入れて、できるところからどんどん書いていきます。
編集者やレビューアといった関係者と原稿を共有するの際は、 彼らにGitHubのアカウントを教えてもらって、リポジトリのコラボレータになってもらいます。上述の通りIT技術の本なのでGitHubを使える関係者が多いからできることです。他の分野の本だとこうはいかないでしょう。たぶん。
関係者からのコメントはissueないしPRの形で受け入れます。このとき、「こんな観点でレビューしてほしい。こんなコメントはissueで、こんなコメントはPRで欲しい」といったレギュレーションを最初に決めてREADMEに書いておきます。
ほとんどのコメントはissueの形で受け取ります。たとえば「ここの段落は意味がわからない」と指摘してもらって、対応するPRを私が作って、コメントをした人に受け入れてもらったらマージ、というやりかたです。
レビューアになんでもかんでもPRを作ってもらうというやり方は非効率だと考えています。理由は、文書は人によってかなり個性が出ること、最終的な成果物は一人の個性で統一されていると読みやすいと考えていること、他の人の個性が反映された文書を自分の言葉に置き換えるコストが大きいことです。ただし、誤字脱字、技術的誤りといった変更点が自明なコメントはPRを出してもらって修正案をそのまま受け入れるというやりかたがうまく機能します。
原稿のファイル形式はmarkdownが多いです。テキスト形式で表示してもある程度読める、覚えることが少ないため書くのが楽、GitHubがhtmlにレンダリングする機能を持っているのでプレビューもしやすい、といった理由で選択しています。関係者も読み書きできることが多いのも利点です。ただし最近は、markdownと同様の利点を持ちつつ、ややマイナーですが、より表現力が高いasciidocに乗り換えつつあります。なお、asciidocもGitHubがhtmlにレンダリングして表示してくれます。
サンプルコードを挿入するときはベタ書きだと管理しにくいのでコードを単体でファイルにしておき、文書ファイルからはコードに対応するファイルを参照します。こうすると後からコードを変更しやすい、コードのテストが容易、出版後にソースコードだけ公開することになったときに自動で公開用のリポジトリを作成、更新するのが楽といったメリットがあります。
画像はGoogle Drawingsで書き、画像形式にexportしたバイナリをGitリポジトリに突っ込んでいます。Gitリポジトリへのバイナリの保存は忌み嫌われがちですが、どのみち大したサイズではないし、頻繁に書き換えるものではないので気にしてません。
本記事は私が書籍を書くときにGitHubで原稿を管理する方法を紹介しました。書籍を出したいと思っている人、すでに出して次もやりたいと思っている人のうちの誰かに刺さることを願っています。
