2015年の技術本執筆環境

2015年は「Laravelエンジニア養成読本」「Laravelリファレンス」、そしてまだ未発表ですが、もう一冊の技術本の執筆に参加しました。

時代によって技術本の執筆環境も変化してきています。今年、技術本の執筆に利用したツール、サービスを紹介します。

過去の技術本執筆環境は、以下のエントリにあります。

• いまどきの技術本執筆環境 – 「CakePHP2実践入門」

このエントリは、Laravelリファレンス Advent Calendar 2015 の21日目です。

ツール、サービス

執筆に利用したツール、サービスは以下です。下記では、今年導入したツールについて書いてみます。

• 執筆: Vim + PhpStorm / Marked 2
• 原稿管理: GitHub（private repository）
• 連絡: GitHub Issue / ChatWork
• CI: レビューファイル自動生成
• 校正: Acrobat Reader DC

執筆: PhpStorm

原稿は Markdown で書くので、これまで Vim を利用していました。

これを、PhpStorm に Markdown Plugin をインストールした環境に変えました。

すっかり PHP を書くには、PhpStorm を使うことが習慣となったことで、細々とした操作を普段から慣れているツールでできるのが快適です。

PhpStorm には、スペルチェックの機能があるので、下記のように警告でミススペルを教えてくれるのが便利です。

PhpStorm で Markdown を書くというアイデアは、「Laravelリファレンス」の共著者でもある @omoon さんから教えてもらったのですが、思いの外快適なので、その後は Blog を書くのも PhpStorm を使っています。（もちろん、このエントリも、です:)）

ただ、プレビューについては、PhpStorm もそれほど良くないので、原稿の確認は、Marked 2 を使っています。

連絡: ChatWork

著者、編集、出版社とのやり取りに ChatWork を使いました。

書籍によっては、GitHub Issue のみで完結するものもあったのですが、相談しながらという形だとチャットツールが軽快で良かったです。

著者間（エンジニア）に限定すれば、Slack でも良いのですが、それ以外の人と一緒に進めるなら ChatWork の UI は馴染みやすく抵抗なく使ってもらえますね。

執筆時は、何かとタスクが発生するので、チャットコメントをすぐにタスクにできるのも便利です。

CI: レビューファイル自動生成

CI で、レビュー用のファイルを自動生成しました。

原稿は Markdown ですが、レビューの際はレンダリングされた形の方が読みやすいので、pandoc を使って HTML 化し、それを Dropbox で配信しました。

pandoc は、Haskell で書かれたマークアップフォーマットの文書を多様なフォーマットへ変換するツールです。GitHub Flavored Markdown にも対応しており、GitHub 上で見るのと似た形式で出力できます。

実際のところ、pandoc コマンドを PHP から実行しているのですが、pandoc だけで見ると、下記のようなコマンドを実行しています。

$ pandoc foo.md -f markdown_github-autolink_bare_uris-raw_html -s --self-contained -t html5 -c /path/to/github.css -o foo.html

また、画像の埋め込みも可能なので、HTML ファイルだけ開けば図やキャプチャ画像も表示できます。

Dropbox へ配信することで、レビュワーは常に最新の原稿を取得できます。自分で git clone などで更新する必要が無いので楽です。

校正: Acrobat Reader DC

校正は PDF で行うことが多かったのですが、これまで使っていた プレビュー.app を Acrobat Reader DC に変更しました。

これは「Laravelリファレンス」の編集の方に教えていただいたことで、プレビューだと校正した位置がずれたり、狙った位置に校正しにくい場合があったのですが、Acrobat Reader を使うことでかなり解消しました。

今後取り組みたいこと

今後、執筆する際は、下記のようなことを取り組んでみようかと考えてます。

• （Yahooの校正支援 API）を使った CI
• リスト（コード）を自動抽出して、GitHub リポジトリに公開（サンプルコード公開用）
• リスト、図表ナンバリングの自動化
• RE:View で原稿書く

さいごに

技術本の執筆（技術本に限ならないと思いますが）では、何と言ってもレビューワさんの存在が大きいです。自分では、気づけない間違いや伝わりにくい言い回しなど、ビシバシ指摘して頂けるのは本当にありがたいです。原稿のレビューありがとうございました！

まだまだ自動化して効率的にできないかを模索中なので、良いアイデアがあれば教えていただけると嬉しいですm( )m

Laravel リファレンス[Ver.5.1 LTS 対応] Web職人好みの新世代PHPフレームワーク