実例でみる技術書執筆の流れ
技術本の執筆・商業出版する機会に恵まれたので、 エンジニアリング組織開発 （以下 EOD） の実例を交えながらその流れや Re:View、執筆に関わる Tips について触れる。
執筆の流れ
技術書の執筆から出版までの一般的な流れは、以下の通り。
- 企画
- 執筆
- 校正
- 表紙デザイン・タイトル
- イラスト清書
- 組版
- 製本
企画
「どのようなトピックを、誰を対象に執筆するか」を決めるフェーズ。 本の企画は、出版社から著者へ執筆依頼がある場合と、著者が企画を持ち込む場合がある。
商業出版においては、出版社の企画会議での承認が必須となる。 企画書には目次を提示する必要があるため、この段階では、構想の相談から目次作成に至るまで、 編集者と複数回やり取りを行い、企画書として形になるための情報を整理する。
私の場合、技術カンファレンスの懇親会で編集者の方にお会いした際に、
本の執筆に興味があることを伝えたところ、後日連絡があり、話が具体化した。
執筆への興味は以前からあり、当時は EOD の 1 章分のドラフト（第7章 サービス安定稼働のためのプロダクションサポート をまとめていた）
と途中までの目次があった。
「ある程度全体が書けてから出版社に持ち込もう」と考えていたが、急遽、全体構想を固めることになった。
執筆
企画が承認されれば、執筆フェーズに入る。
執筆の期間
執筆期間は、最終的には著者の意向によるところが大きいが、EOD の場合は「3 週間で 1 章を執筆する」という前提で、 6 ヶ月の執筆期間を設けたロードマップを作成した。
最初に構成を詰めるか、すぐに本文を書き始めるかという選択肢があったが、 この段階では「この節で本当にこの内容に踏み込めるか分からない」というレベルのイメージしかない部分も多かったため、 全体の解像度が高まることで構成の組み換えの必要性が見えてくると考え、まずは本文を書き始めることにした。
執筆の方法
執筆方法について、特に指定はなかった。 著者が多岐にわたるため、MS Word、Google Docs、Markdown ファイルなど、 文字さえ書ければ何でも良い、という雰囲気を感じた。
私は次の点から、Re:View を用いた。
- 本のフォーマットでの出力が容易
- 執筆過程を Git 管理可能
- PDF や EPUB 形式の出力が可能
Re:View については後述する。
執筆における GitHub の活用
GitHub のプルリクエストは、執筆においても非常に便利だった。 Google Docs の提案・コメント機能でも生産性は確保できるが、章ごとにファイルを分割しないと管理が難しくなる可能性がある。 Git を使い慣れているエンジニアであれば、GitHub でアウトプットを管理するのは良い選択肢だ。
企画成立前の目次確認は、PDF に対するコメント機能で行ったが、UI の問題で見通しが悪く、PDF を再生成するとコメントが消えてしまうという問題があった。 そのため、簡単なものでなければ PDF へのコメント機能での継続的なやり取りは避けた方が良いだろう。
アウトプットを GitHub で管理するにあたり、ブランチ戦略は迷うところだった。 章ごとに記述するため、章ごとにブランチを作成することも考えたが、シンプルさを重視し、以下の運用にした。
- 執筆は
mainブランチで進める - 編集者が気になるポイントは
mainを見て Issue をつくる - 編集者が修正を行う場合は専用ブランチを作成しプルリクを作成する
著者視点では、この運用はやりやすかった。 執筆中に、後の章の内容を受けて前の章との整合性を取ったり、後から思いついた内容を追記したりすることはよくある。 章ごとにブランチを分けても、どうせ複数の章が混ざることになり、仮に厳密に章ごとにブランチ化しても、変更が分散してビルド時にすべての変更が入らず、見通しが悪くなることが想定された。
Re:VIEW は CI/CD も可能で、GitHub Actions を用いて on_push をトリガーに PDF をビルドし、Artifact にアップロードする形にしていた。
執筆に関わる所感
章の大きさの方針
執筆を進める中で気づいたことだが、章の大きさは書籍によってかなり異なる。 EOD は 1 章あたりのボリュームが大きい構成になったが、例えば『Google のソフトウェアエンジニアリング』では、EOD における項レベルのトピックが 1 つの章となっており、 全体で 25 章、さらに各章は部で分類されている。
このあたりは著者や編集者の意向、好みによるところが大きいが、章を細かくすると、章・節・項の「項」レベルで出せる内容も細かくなり、目次での見通しが良くなる。
小見出しは積極的に導入する
章・節・項（1.1.1 のような番号付き見出しがつく）に続く、番号を与えられない小見出しは、当初あまり使用していなかったが、読者にとってあると嬉しいものだと気づいた。
執筆中に参考文献を眺める際、ページを早送りしながら流し読みをすることがあったが、 優れた書籍は、章・節・項のタイトルと小見出しを眺めるだけで、その主張のおおまかな内容が理解できることに気づいた。
「このブロックには何が書いてありますよ」という説明は多ければ多いほど読者は助かるため、伝えたい主張があるタイミングでは、小見出しを積極的に挿入すると良いだろう。
章ごとのまとめ
EOD では、各章の最後にまとめの節を設けた。 章ごとのまとめの有無は、本によって異なる。 執筆中に「本当に必要か？」と迷う場面もあったが、想定読者層を考慮し、忙しい方々がまとめで概要を掴んだり、 熟読すべき箇所を判断したりするのに役立つことを期待して残した。 このあたりは著者の好みや本の属性次第だろう。
校正
執筆した内容は、校正によってさらに磨かれる。 EOD の校正は、編集者さんが章ごとにプルリクエストを作成し、意図や認識のずれがないかを確認しながら進めていただいた。
基本的には書き終えた章から校正を進めるが、執筆中に過去の章に修正を加えたくなることもある。 そのため、変更が git でコンフリクトしないように、校正用のブランチでの作業開始前に main ブランチをマージしてから進めてもらうのが望ましいだろう。 このあたりのコミュニケーションは、開発プロセスとも共通する部分がある。
全体を一通り校正し、調整フェーズに入った校正の終盤では、それまで main ブランチへ直接 push していた著者側の変更もプルリクエストを作成する形にし、 編集者さんの確認を経てマージするようにした。
イラストや組版など、すべての要素が出揃った段階で Proofreading （プルーフ校正）が行われ、完了次第製本作業へと進む。
表紙デザイン・タイトル
表紙デザイン・タイトルは執筆の終盤、校正や組版中などのタイミングで行われる。 いずれも最終決定権は編集者さん側にあるが、意見のヒアリングは行われる。 いくつかの案が提示され、特に「絶対に避けたいもの」は選べる。
イラスト清書
著者が提示した下書きは、編集者の方へ渡すと清書されて返ってくる。 私は Draw.io などの描画ツールでイメージを作成したが、手書きでも問題ない。
組版・製本
組版は、書籍としての体裁を整える作業であり、DTP（Desktop Publishing）の専用ツールを用いて行われることが多い。 EOD では Re:VIEW を使用していたため、LaTeX をそのまま用いて紙版・電子版の組版を行っていただいた。 LaTeX による組版は通常より早いようで、作業開始から 1 ヶ月弱で印刷に進んだ。
ここまでの作業がすべて完了すると、印刷に入る。 まずは PDF などの出力されたものを試し刷りし、修正を経て完成品の印刷が行われる。 組版作業中は、著者はやり取りを見守るだけで、直接的な作業は発生しなかった（GitHub Action のビルドスクリプトを組版専用には変更した）。
Re:View について
Re:VIEW は、エンジニアであればすぐに馴染めるツールだ。 Markdown とは少し異なる独自のマークアップ記法を用いて記述するが、Markdown から Re:VIEW フォーマットへの変換、あるいはその逆も可能。 ビルドすることで書籍フォーマットの PDF が生成されるため、「本を書いている」という実感が湧きやすい。
Review のキャッチアップには次の資料を用いた。
Review の利用
Review は Starter Kit など、いくつかのテンプレートが存在する。
私はFirstStepReVIEW-v3を参考にリポジトリを整えて執筆を開始した。
PDF のビルドは、必要な依存関係がすべて含まれている Docker を用いて実行すると、依存関係の管理でつまづくことなくビルドできるためおすすめだ。
記法
チートシートには基本的なマークアップ記法が記載されているため、慣れないうちは非常に役立つ。
一方で、章タイトルを引用する @<hd> のような記法の記載はないため、表現力を高めるためにはフォーマットガイドにも目を通すことをおすすめする。
まとめ
本記事では、技術書の執筆プロセスと Re:VIEW について紹介した。 本の書き方には著者の好みがあり、「これが絶対的な正解」というものはない。
執筆経験がないと、手探りの部分が多く、どのように進めれば良いか分からないこともあるが、 実際に書いてみると、普段から文字を書いている人にとっては執筆という行為自体はそれほど難しくないことに気づく。 ただし、内容に価値のある本が書けるかどうかは別問題だ。
普段、あまり世の中に情報発信しないエンジニアの中にも、特定の分野で高い専門性を持っている方は多くいる。 そういった方々が本を書くことで喜ばれる読者層は一定数いるはずだ。 あまり身構えずに、ぜひ技術書の執筆に挑戦してみてほしい。