技術書を書いたハナシ

React Native Japan で @besutome 、 @YutamaKotaro と技術書典 3 で技術書を書いたのでその作業内容を記録しようと思う。
出した本はこちら。 PDF 形式で配布している。

https://rnjapan.booth.pm/items/665275

おおまかに次の流れで作業した。

1. 原稿を書く + 校正作業
2. レビュー
3. Re:VIEW 形式への変換
4. 装丁 + 微調整

次で各手順について書いていく。 textlint と Re:VIEW Template は素人が使っても確実に威力を発揮するので強く使用を推奨。

原稿を書く + 校正作業

原稿は markdown で書いて git で管理した。今回は複数人で書いたので github に repo を作ってそこで共有。

原稿を書く際は先に textlint と日本語用のルールをセットアップして、日本語として不自然にならないかチェックしながらやった。非常に有用なので使用をおすすめ。

• http://efcl.info/2015/09/10/introduce-textlint/
  • https://github.com/textlint/textlint
  • https://github.com/textlint-ja/textlint-rule-preset-japanese
  • https://github.com/textlint-ja/textlint-rule-preset-JTF-style

もひとつ、 textlint で一緒に表記ゆれもチェックできるのでやってみたがこちらも必須と言っていいものだと思う。

• http://efcl.info/2015/09/14/textlint-rule-prh/
  • https://github.com/textlint-rule/textlint-rule-prh
  • https://github.com/azu/textlint-rule-spellcheck-tech-word

今回は書く内容にあわせて次のように辞書ファイルを追加して使ってみた。

---
version: 1
rules:
  - expected: React Native
    pattern: /[rR]eact ?[nN]ative/
  - expected: DDD
    pattern: /[dD]{3}/
  - expected: Redux
    pattern: /[rR]edux(?!-)/
  - expected: Zeplin
    pattern: /[zZ]eplin/
  - expected: Web
    pattern: /[wW]eb/
  - expected: 例えば
    pattern:  /たとえば/
    specs:
      - from: たとえば
        to:   例えば

ポイントは Redux のところ。技術としての Redux は先頭大文字ではじめたいが、 redux-saga などのライブラリ名は小文字ではじめたいのでハイフンが後ろについている場合はマッチしないように先読み否定を使っている。

  - expected: Redux
    pattern: /[rR]edux(?!-)/

レビュー

3 人で書いたので交互にレビュー。わかりにくいところがスッキリしたり、内容がブラッシュアップされるのでひとりで書く場合でも誰かにレビュー依頼したほうがよいかも。

Re:VIEW 形式への変換

md2review を使って markdown から Re:VIEW 形式に変換した。

https://github.com/takahashim/md2review

markdown がきちんと書かれていればまったく問題なく変換される。変換後のファイルがちょっとおかしいな ? と思った場合は markdown 側を確認。特にコードハイライトなど範囲にまたがる書式指定が混乱しがちなので重点的にチェックするといい。

画像を使っている場合はここで一緒にコピーする必要がある。<章名>-<画像名>の形式でないとRe:VIEW が認識してくれないので後段の装丁作業でエラーが出た場合は要確認。特にエラーが多かったのが画像のコピー忘れだった。

装丁 + 微調整

装丁作業には Re:VIEW Template を使用した。

https://github.com/TechBooster/ReVIEW-Template

インストール、特に Tex のセットアップに時間がかかったので早めに準備しておくとよい。今回は使わなかったが、 Docker 版を先に試すのがよいかも。

https://github.com/TechBooster/ReVIEW-Template#docker%E3%82%92%E4%BD%BF%E3%81%86

大体 markdown での記述で本として必要なものは揃うのだが、画像サイズの微調整だけは変換後の Re:VIEW 形式ファイルを直接いじる必要があったので注意。詳しい使い方は TechBooster さんが本を出しているので参照するとスムーズかも。

https://techbooster.booth.pm/items/586727

実際に困ったことがあったときはまずこれを検索、それでもわからないときに Google 検索、ということですべて乗り切れた。感謝。

奥付や表紙など、その他の設定についても記載されているので手元に一冊あるととても安心。

PDF への変換は npm scripts の npm run pdf を使ってやった。 PDF だけならこれだけでもまったく問題ない。別途 epub が必要という場合は review-epubmaker コマンドを使うだけでよかった。こちらもすごいわかりやすい。

やってみて

いまは簡単に本が書けてしまう時代なんだなあと実感。各種ツールを提供してくださっている azu さん、 TechBooster さんありがとう !!