デジタル事業情報サービスユニットの石原です。 普段はデータサイエンティストとして、主にサービスの企画・開発に関わっています。

筆者は2020年3月、講談社から『Pythonではじめる　Kaggleスタートブック』（石原祥太郎／村田秀樹・著）[1]という書籍を出版しました。 筆者が社外活動として取り組んでいる世界規模の機械学習コンペティション「Kaggle」の入門書です。

本章では、プログラマとして働きながら技術書を執筆した筆者の経験を基に、次の6つの観点で商用出版で用いた便利なツールを紹介します。 今回の執筆には、普段プログラマとして働いている際に活用している便利なツールを可能な限り転用しました。 技術書の執筆に興味関心のある読者を対象としています。

• Re:VIEWでの原稿作成
• GitHub + Dockerでの再現性担保
• GitHub Pull Requestでの相互レビュー
• GitHub Issuesでのタスク管理
• Google Sheetsでのメモの共同編集
• Slackでのコミュニケーション

Re:VIEWでの原稿作成

執筆の段階では「Re:VIEW」[2]という文書作成ツールを活用しました。 Re:VIEWを用いると、段落や箇条書きなどをプログラマに馴染みの深いマークダウンのような記法で指定し、PDFなどの形式で出力できます。 参考文献・コードブロック・数式など技術書を書く上で必要不可欠な要素を備えているのも魅力的でした。

Re:VIEWは、弊社のプログラマ有志が技術書の祭典「技術書典」で販売している『Nikkei Development Book』の作成にも利用されています。 筆者は2018年10月に開催された「技術書典5」[3]での執筆時からRe:VIEWを使用し、使い心地に満足していたのも決め手の一つでした。

GitHub + Dockerでの再現性担保

今回の書籍は共著だったため、何らかの手段での原稿管理が必須でした。 2人とも普段から業務や個人活動でGit[4]およびGitHub[5]を利用していたので、自然と今回の執筆でも導入を決めました。

Gitはバージョン管理システムで、GitHubはGitの仕組みを利用したウェブサービスです。 共に2020年現在、多くのプログラマが利用しています。

今回は文章や画像などのファイルを、下図のようなGitHubリポジトリにまとめて管理しました。

主要なフォルダ・ファイルの概要を次の表に示します。

フォルダ・ファイル名	説明
images	画像ファイルを配置するフォルダ
notebooks	notebook形式のファイルを配置するフォルダ
bib.re	参考文献を記載するファイル
catalog.yml	出力の章の構成を定義するファイル
chap00-preface.re	まえがきを記載するファイル
chap01.re〜chap05.re	第1〜5章を記載するファイル
chap99-postscript.re	あとがきを記載するファイル
config.yml	体裁などを設定するファイル

GitHub上でファイルを管理しておくことで、次のような利点があります。

• ファイルの変更履歴を保持し、過去の状態に戻すことができる
• 複数の筆者の編集で内容に食い違いが生じないようにクラウド上に一元管理できる

ファイルだけではなく「Docker」[6]を用いて実行環境構築の再現性も担保しました。 Dockerを用いると、自分の端末にゼロから仮想的な環境を立ち上げることが可能です。

技術書の執筆は、数カ月にもわたる長期間の取り組みです。 GitHubとDockerの両者を利用することで、仮に自分の端末が突然壊れた場合にも対処できるよう、できる限り再現性を保つように意識していました。

GitHub Pull Requestでの相互レビュー

お互いの編集内容のレビューには、GitHubの「Pull Request」機能を使いました。 Pull Requestは、修正内容を提案・承認する機能です。

下図の場合、私が原稿を修正し、共著者の村田さんにレビューをお願いしています。

変更前後の差分を分かりやすく確認できる点、修正内容単位でコメントをやり取りできる点などが魅力です。 下図のPull Requestでは、文中の「著者」を「筆者」に変更しています。 このように変更内容をお互いに把握しながら進めることで、無駄な修正を重ねてしまう事態を避ける利点があります。

GitHub Issuesでのタスク管理

執筆に関するタスク管理には、GitHubの「Issues」機能を使いました。

タスクを「Issue」という単位で書き起こし、担当者を割り振っていきます。 個々のIssueは、一つのPull Requestに紐付ける形で処理していきました。

執筆・レビュー・タスク管理がGitHub内で完結しており「取りあえずGitHubを見ればよい」という状況を心掛けていました。 余計なことを考える時間を極力減らし、良い文章を書くという部分に思考のリソースを注力できたと感じています。

Google Sheetsでのメモの共同編集

GitHubが提供する機能では使いづらい部分に関しては、別のツールを使っていました。 例えば、表形式でのメモの管理には「Google Sheets」[7]を利用しました。

Google Sheetsでは、Excelのような表形式の情報をオンラインで管理できます。 共同編集も可能で自動的に定期的なバックアップを取ってくれるのも魅力的です。

今回は、レビュワーや献本先の情報を共同編集していました。 出版社の編集者に共有する際にもリンクを伝えておくだけで常に最新版を連携でき、円滑にやり取りできたと思います。

Google Sheetsを作った際には、忘れずにGitHubに対応するIssueを立てておきました。 IssueにGoogle Sheetsへのリンクを貼ることで、情報をGitHub内に集約する狙いがあります。

Slackでのコミュニケーション

日々の細やかなコミュニケーションには「Slack」[8]を使いました。 Slackは、主にビジネス向けのチャットツールです。 弊社でも日常業務のツールとして導入されており、筆者も使い慣れています。

Slackでは、話題に応じた複数の「チャンネル」を作成できます。 チャンネルごとに公開・非公開を設定できるのも利点の一つです。 今回は、下図のようなチャンネルを用意していました。

主要なチャンネルの概要は、次の表の通りです。

チャンネル名	説明
general	全員が入る
github-notification	GitHubに関するPull RequestやIssueに関する通知を流す
kaggle-book	基本的なやり取り
random	雑談用
review_*	レビュワーとのやり取り
times	当日の作業内容などを垂れ流す

他にも、書籍内の対談をチャット形式で作成するチャンネルも利用していました。 これらのチャンネルは執筆を終えて不要になった段階でアーカイブしていました。

Slackはメッセージ単位でリンクを発行できます。 必要に応じて、GitHubのIssueに関連するSlackのやり取りのリンクを貼って情報を集約していました。

おわりに

本章では、技術書を執筆した筆者の体験談を基に、商用出版で用いた便利なツールを紹介しました。 紹介した内容が、皆さまの今後の技術書執筆に少しでも役立つことを祈っています。

謝辞

本稿は、題材となった書籍の共著者である村田秀樹さん（@currypurin）にレビューをしていただきました。 書籍本体の執筆を含めて、多大なご協力を頂いたことを、心よりお礼申し上げます。

参考文献

[1]: 実践Data Scienceシリーズ PythonではじめるKaggleスタートブック, https://www.kspub.co.jp/book/detail/5190067.html (accessed 6 November 2020).

[2]: Re:VIEW, https://github.com/kmuto/review (accessed 6 November 2020).

[3]: 技術書典5, https://techbookfest.org/event/tbf05 (accessed 6 November 2020).

[4]: Git, https://git-scm.com/ (accessed 6 November 2020).

[5]: GitHub, http://github.com/ (accessed 6 November 2020).

[6]: Docker, https://www.docker.com/ (accessed 6 March 2020).

[7]: Google Sheets, https://www.google.com/sheets/about/ (accessed 6 November 2020).

[8]: Slack, https://slack.com/ (accessed 6 November 2020).