Zenn
😎

技術本を書いてみた

2020/12/25に公開
#
review
#
執筆
#
アドベントカレンダー
#
prh
#
技術本
tech

このブログは Recruit Engineers Advent Calendar 2020 25日目の記事です

皆さんメリークリスマス。Kumaです。
ちょうど昨日が締切だった、技術書典10に出す本の作成が終わったので、本ブログでは、最近の技術書を書く環境についてまとめ、みなさんもどんどん技術書を通して技術をアウトプットしてワイワイしようぜ！といういざないをしてみたいと思います。

今年はGCPやクラウド系の記事は封印です…

巨人の肩の上に立つ

卒論、修論、学術論文を書いた思い出ってありますか？僕はあります。TeXの記法を覚えて、LaTeX環境を整え、Eclipseを使ってヒーヒー言いながら書いていた覚えがあります。僕の同期は、Microsoft Wordで、全角と半角スペースを駆使しレイアウトを作りながら、加筆修正するたびに項目の番号や、図の番号を手動で訂正していて爆死していたことを覚えています。違う同期は、テキストエディタで頑張って編集したが、Macのハードディスクがお亡くなりになり、バックアップも取っておらず…みたいなことも今では懐かしい思い出です。

もしあなたもこのような苦労をして、にがーい思い出があると、ついつい本や論文を書くことにかなりの抵抗があるのではないかと思います。しかし、昨今の技術書を書く環境はとてつもなく発展していて、とても快適です。

具体的には、

  • Git（GitHub）
  • prh
  • デジタル出版ツール Re:VIEW
  • 先人たちの知恵と知識が詰まった全部入りのテンプレート
  • 先人たちの知恵と知識が詰まった全部入りのDockerコンテナ

を、使わせていただくことで、ストレスフリーな、執筆に集中できる環境が整います。

環境構築

必要なものを用意する

今回は、

  • macOS Big Sur（11.1）
  • Visual Studio Code（1.52.1）

を使用します。

エディタはなんでもよいのですが、prhを簡単に使えるという観点からVisual Studio Codeを用いて解説します。

prhをインストール

prh とは、校正を手伝ってくれるライブラリです。校正ルールにしたがって、ルール違反をしていたら知らせてくれます。

エラー表示例

npmで各種ツールを簡単にインストールすることが可能です。

sh
npm install -g prh
sh
npm install -g prh-languageserver

その後、prhのVisual Studio Code用のextensionをインストールします

先人たちの知恵と知識が詰まった全部入りのテンプレートをforkしてcloneする

TechBooster/ReVIEW-Template をforkし、ローカル環境にgit cloneします。

先人たちの知恵と知識が詰まった全部入りのDockerコンテナをpullする

sh
docker pull vvkame/review:5.0

これで準備は完了！あとは書くだけです。

それでは書いてみる

もしかして、TeXとか使うの…？

最終的にTeXを使うことになるのですが、意識することはほとんどありません。そして、TeX記法では書きません。慣れ親しんだMarkdownに似たRe:VIEW記法で書きます。

Re:VIEWとは

Re:VIEWとは、

Re:VIEWは電子書籍と紙書籍のための、簡潔かつ強力なデジタル出版ツールです。コンピュータ書等の技術書籍（紙・電子）の商業出版や同人出版に利用されています。

https://reviewml.org/ja/

というものです。Re:VIEWを使うためには独自の記法を使いますが、Markdownに慣れた人なら難なく学習できます。記法はここから確認できます。

とにかくやってみよう

習うよりなれろ、とにかくやってみましょう。

まず、forkしてcloneしたテンプレートのルートをVisual Studio Codeで開きます。
さまざまなファイルがありますが、基本的に編集しないといけないファイルは3種類しかありません。

articles/*.re

本の本文を構成するファイル群です。1章ごとに1ファイル作成します。

articles/catalog.yaml

各章のファイルがどのような順番に並ぶべきかを設定するファイルです。
テンプレートには、

yaml
PREDEF:
  - preface.re

CHAPS:
  - article.re

APPENDIX:

POSTDEF:
  - contributors.re

と書かれていますが、もう見るだけでわかりますね。

articles/config.yaml

本の各種設定を行うファイルです。
テンプレートには丁寧にコメントが書かれているので、コメントを見るだけでどのように表記すればよいかが一目瞭然です。

本を作ってみる

では、いったんテンプレートのまま、実際にPDFを出力して感動してみましょう。
Terminalを開いて、テンプレートのルートにある、 build-in-docker.sh を実行します。
しばらくすると、 articles/ ディレクトリ配下に ReVIEW-Template.pdf が出力されていると思います。開いてみてください、こんなに簡単にこれが出力できるのか！？！？！？と驚きました。

prhを使って自動校正する

もし、上記の手順を正しく行っていたら、もうすでに自動校正が実行されていると思います。校正ルール定義ファイルは prh-rules/ ディレクトリ配下に存在するので、必要に応じて編集します。

本を書くとき、どのようなフローで書きすすめるか

もし一人で書く場合は適当に進めたらよいでしょう。しかし、複数人で書く場合、誰と書くかによってフローを考えます。

全員エンジニアの場合

コードを書くように、書きましょう。GitHubを使ってバージョン管理をして、レビューして、もししたかったらGitHub Actionsを設定しておきましょう

全員がエンジニアではない場合

全員でRe:VIEWを使わず、まず、Google Docsなどで文章を書き、レビューし合いましょう。そして、脱稿後にできる人が各種ツールを用いて、校正し、Re:VIEW記法に直して、PDFを出力しましょう。
新しいことを学んでもらうよりも、原稿に集中してもらうべきです。あなた自身も、記法やGitHubの使い方を教えることに労力を割くのではなく、原稿に集中しましょう。

実際に本をかいてみて

こんなブログを書いておいて今更ですが、僕は今回、初執筆、初出展でした。
最近、技術書典もそうですが、このブログをホストしていただいている Zennにも本を販売する機能があったり、本を書く機運が高まっていました。
ブログをちょこちょこ書いたり、どこかに登壇したりすることはあったのですが、実際に本を書いてみて感じた感想を記して締めくくりたいと思います。

ある程度まとまった単位でのアウトプットができる

このブログももうすでに長文になりつつありますが、本というフォーマットなので、数十ページの分量のアウトプットが一気に可能です。構成を考えつつ、まとまった単位の知識が網羅的にアウトプットできるというところに魅力を感じました。

協業して執筆できる

何かを成し遂げたとき、自分ひとりだけで完結したということは、ほとんどないんじゃないかと思います。僕が今回書いた本の内容も、複数人数でやり遂げたものです。他のメディアだと、分量や形態から、協業してアウトプットすることが非常に難しい中、章を分担して、自分が担当したことをとりあえず書く、あとから構成する、というざっくりとした決め事をするだけで、協業してアウトプットが作成することができました。当たり前っちゃ当たり前なんですが、単純に感動しました。

世に出せる、フィードバックをもらえる

著名なプラットフォームに乗せてもらうことで、少しでもそのアウトプットを人々の目にさらして、フィードバックが得られる機会を増やすことが可能になります。もちろんそれが本が売れた金銭的なものかもしれないし、もしくはTwitterのDMかもしれません。
フィードバックがもらえることは非常に貴重なので、その機会を少しでも増やすためにも、全方位的にアウトプットすることが重要なんじゃないかと思いました。とか言ってまったく無かったらどうしよう…

まとめ

  • 先人たちの知恵と知識によって、本はメチャクチャ簡単に出力できる
  • 執筆環境を整えるのもめちゃくちゃ簡単
  • 本というフォーマットは、ブログとは違った魅力がある
  • アウトプットを積極的にして、フィードバックをもらう機会を増やそう！

それではまた来年！

Special Thanks

@vvakame

Discussion