Home > book | CakePHP > いまどきの技術本執筆環境 – 「CakePHP2実践入門」

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

この記事の所要時間: 525

共著で執筆に参加した「CakePHP2 実践入門」が2012/09/29に出版されました。



2007年に執筆した「CakePHPガイドブック(共著)」から数えて4冊目の書籍執筆となるのですが、執筆の方法やコラボレーションのツールも大きく変わりました。執筆を終えて一息ついた今、執筆環境を振り返ってみたいと思います。

2007年と今回の執筆環境をざっくりと比較するとこんな感じでした。

原稿執筆 原稿提出 連絡 issue管理 CI
2007年 Word FTP ML ML なし(Wordで確認)
2012年 Vim + Marked Github Facebookグループ Github Githubリポジトリをpollingして、Markdown+独自マークアップをHTMLにコンバートなど。

原稿執筆

原稿は Vim で書いて、Marked のプレビューを確認するという形で進めました。

Vim

原稿の形式は、Markdown+独自マークアップのプレーンテキストだったので、執筆陣は各自好きなツールを使うことができました。

Vim は普段から使っていて慣れていますし、技術本ということでソースコードを読んだり書いたりする場面が多いので同じエディタ上でそれができるのは楽でしたね。

Markdown ということで当初は専用のエディタなども試したのですが、やはり「書く」という行為に関しては手に馴染んでいるものが一番です。

Marked

Marked は Markdown 形式で書かれたファイルをプレビューするツールです。Marked でファイルを開いておくと元ファイルが変更されるとプレビュー側も連動して更新されます。

あくまでプレビューに特化したツールなので任意のエディタと組み合わせて使用することができるのが良いですね。

実は Vim + Marked の組み合わせが気に入ったので、この blog も同じ構成で書いています。

以前は Word だったので、プレビューという点では問題無いのですが、ソースコードが書きにくかったり、差分が取りづらかったりしていました。当時はそれが当たり前だと思っていましたが、やはりプレーンテキストで書けるのは慣れてる分、楽でした。

原稿提出、issue管理

Github

原稿提出やissue管理にはGithubを使いました。

執筆陣は各々原稿を書いて、Github へ push して原稿を提出するという流れでした。

git のメリットは言わずもがなですが、こちらも日常でソースコードを push するのと同じ感覚で原稿を提出できたのは良かったです。さらに原稿がプレーンテキストということで、差分を確認したり、変更履歴を見たりというのもお手のものでした。

今回は章ごとに執筆者が決まっていたので、conflict することも無いだろうということで、ブランチ分けはせずに master へpushしていました。

原稿の修正依頼や査読結果などの issue 管理も Github で行なっています。

Github の issue 管理では、commit ログに issue no を記載することで issue チケットから commit にリンクを貼ることができるので、issue に関する修正が明示できて、これは便利でした。

本書のサンプルコードもGithub上で公開する予定ですので、書籍を購入された方はご参照下さい。

連絡

Facebook

編集の方、執筆陣との連絡には Facebook グループを使いました。

ML でも良かったのですが、メールより気軽に投稿、返信ができたのでやりやすかったです。返信するほどではないけど同意や見たことを現したい時に「いいね!(Like)」で反応できるのは手軽で便利ですね。

ただ Facebook グループだとどうしても過去の発言が流れて行ったり、一つのトッピクについてコメントが大量についたときに見づらかったりするので、もし次回があればchatworkなど別のコラボレーションツールの方が良いかもしれません。

CI

CI 的な機能もいくつか用意しました。

Githubのリポジトリをpollingしており、定期的に自動実行されます。

  • PHPコードの自動lint(安藤さん作)
  • 原稿中のソースコード自動抽出(安藤さん作)
  • 原稿をHTMLへ自動変換、変換ブラウザで閲覧可能に(鈴木さん作)
  • 原稿の規約(マークアップや一行文字数等)を検証して、エラーログを出力(鈴木さん作)

特に鈴木さんが用意してくれた原稿をブラウザで確認できるツールはかなり便利でした。書式エラーなどがログとして確認できるので、これを活用して原稿の修正を行いました。いずれ公開されると思うので乞うご期待を。

今にして思うと Jenkins でこういったツール群を管理しても良かったですね。

普段のシステム開発と同じリズムで原稿を書く

今回利用したツールはどれも普段のシステム開発で利用しているもので、ソースコードを書くのと同じリズムで執筆を進めることができました。

執筆期間中に度重なるCakePHPのバージョンアップ(2.0 -> 2.1 -> 2.2)があり、リスケを余儀なくされましたが、原稿のデグレや issue の取りこぼしもなく、無事に書店に並べることができました。

CakePHP は、公式ドキュメントである cookbook が充実しており、和訳も少しづつ進んでいるのですが、日本語で書かれたまとまった情報を望む声が多くありました。この本はそういった機運を受けて執筆されました。みなさんのCakePHP開発の一助になればと思いますので、一度手にとって頂ければ嬉しいです。

最後に、セキュリティ章について丁寧な査読、ご指摘をして頂いた徳丸浩さんにお礼を言いたいと思います。本当にありがとうございました。

Pocket

follow us in feedly

Home > book | CakePHP > いまどきの技術本執筆環境 – 「CakePHP2実践入門」

検索
フィード
メタ情報

Return to page top