黒曜の吹き溜まり

技術書を支える技術

2017-12-15 執筆

この記事は第2のドワンゴ Advent Calendar 2017の15日目です。
14日目の担当はkusumotoaさんの1分で分かるDependency Injection in Swiftでした。

DST(Dwango Standard Time)ならまだ15日なのでセーフってことでお願いします。

📗 技術同人誌について

ここ1年ちょっと、技術同人誌を書くのがマイブームです。

これまでに書いたのは以下の4冊です。

だいぶ薄い本も入ってますが1年と少しの間に4冊の技術同人誌を書くことができました。(ダイレクトマーケティング)

なお年末のコミケでは新刊はないものの、昨年末に続きなのくろと一緒に開発しているにゃんぱす！というサービス関連の何らかの頒布を行います。
既刊も持っていくので、よかったら遊びに来てくださいね。(ダイレクトマーケティング)

そんなわけで、今回は技術書を書いた感想や知見などをつらつらと書いていきます。

🔧 執筆ツール

「にゃんぱす！製作日誌」と「情報ガール」はLaTeXを使って書きました。
一方、「いろんな言語でライフゲーム」と「Re:VIEWで本を書く本」はRe:VIEWを使っています。

Re:VIEWの方がマークアップっぽく書けるので、普通の技術書を書く分にはRe:VIEWの方が楽です。
また、図をコードで埋め込みたい場合でもGraphvizなどいくつかの選択肢があるので、簡単なものなら問題ないと思います。

一方で、ちょっと凝ったことをしようと思うと急に難しくなることがあります。
特に「情報ガール」はTikZでVenn図を描画したり、MusicTeXで楽譜を埋め込んだりといったことをしていたので、Re:VIEWで書くのは厳しいタイプの本でした。
事前に画像作っておいて埋め込むならある程度はいけそうですが、どちらにしろ細かいレイアウトを弄るのはLaTeXレイヤーになってしまうことが多く、それなら最初からLaTeXのほうが楽かな、という気持ちです。

📓 Re:VIEW Scaffold

Re:VIEWで本を書くときに定型設定を毎回入れるのが面倒だったので、scaffoldリポジトリを作っています。
以下ではこのリポジトリの技術的な要素をざっくり説明していきます。

🐳 Docker設定

自宅ではWindowsをメインに使っていて、Ruby環境の整備が面倒なので、最近はほとんどのツールをDockerで導入するようにしています。

Re:VIEWのDockerイメージとしては@vvakameさんのvvakame/reviewがあります。
通常の使い方ならこのイメージを直接使えばいいのですが、「いろんな言語でライフゲーム」ではGraphvizで図を入れたかったので、作図ツールを追加インストールしたkokuyouwind/review-graphイメージを作って使うようにしました。

review-scaffoldではdocker-compose.ymlにイメージやボリュームの定義を書いた上で、binディレクトリ下のスクリプトから docker-compose run経由でreview-pdfmakerなどを呼び出すようにしています。
これにより、使うときは環境によらず./bin/pdfなどの簡単なコマンドでビルドできるようになっています。

🕸 HTMLの生成

Re:VIEWではPDFとEPUBだけでなく、review-webmakerコマンドを使ってHTMLを生成することができます。
PDFのビルドはそこそこ時間がかかるため、ざくざく書いていくフェイズではLiveReloadを仕込んでHTMLを開いておくことで快適に書き進めることができます。

review-scaffoldでは./bin/htmlを実行するとdocsディレクトリに出力されるようにしています。
このためGitHub Pagesを使って簡単に公開できます。
例えば「Re:VIEWで本を書く本」は以下のURLからWebページで見ることができます。

https://kokuyouwind.github.io/review-review/index.html

✅ 自動校正

自動校正は@azさんの技術文書を書くためのtextlint校正ルールセットを参考にしてtextlintを入れています。
これも./bin/lintだけで実行できるのでお手軽。

🤖 CI

CircleCIとReviewDogを使ってlint違反をPullRequestにコメントされるようにしています。

こんな感じで引っかかった内容がコメントされます。

またmasterブランチではPDFをDropboxにアップロードするようにしています。
これにより、いつでも最新の内容をすぐ確認できるようになっています。

この設定は.circleci/config.ymlに書かれているのですが、割と泥臭くやってるだけなので見てもらえばわかると思います。

🙆🏻 技術同人を書くメリット

とりあえず書きたいことを書ける、というのは楽しいです。
また基本的には一貫したテーマについて章・節などの構成を考えながらまとめることになるので、自分の中の知識がだいぶ整理されたり、曖昧だったことを学び直す機会にもなります。

とはいえ、やはり一番の魅力は「物理の本として手に取れる」「頒布を通じて読者と直接話すことができる」ということだと思います。

こういうツイートを見ると、めちゃくちゃ嬉しいです。
ちなみに私はめっちゃエゴサするタイプで、自著に言及してくれたツイートにはひたすら❤を飛ばしてます。

🙅🏻 技術同人を書くデメリット

とりあえず労力は半端なくかかります。
書籍を1冊まとめあげるの、想像以上に大変でした。

また、手間だけでなくお金もかかります。
例えば「情報ガール」は100部刷るのに5万円ちょっとかかっています。
頒布した際に多少代金を受け取れるとはいえ、完売できたとしてもそこまで大きな利益にはならないですし、そもそも名古屋から東京まで往復すると交通費で吹っ飛びます。

なので、少なくとも自分の中では完全に趣味の世界です。
まぁ同人の定義からすると正しい気はしますが。

✍🏻 まとめ

多分4月くらいに技術書典5が来るだろうから、みんな技術同人誌書こうぜ！

第2のドワンゴ Advent Calendar 2017、16日目の担当はyamotukiさんです。

技術書典 情報ガール Re:VIEW
© 2018 by Lednerb
Bilberry Hugo Theme