この書籍を書くことにしたのは、私自身が運営する JSer.info にて、 あなたが読むべきJavaScript Promises | JSer.info という記事を書いた事が始まりです。
この記事を書く際にECMAScript6 Promisesについて色々調べながら書いていましたが、 最終的に扱いきれてない情報もありました。
またこの時、電子書籍はどのようなワークフローで書かれているんだろう？ということに興味を持っていて、 それを学ぶには実際に電子書籍を書いてみるのが早いと思ったのも書き始めた理由の一つです。
一番最初に自分用の今後やりたいTodoを書いているリポジトリにIssueを立てることから始めました。
電子書籍を書くにはどのフォーマットで書くのかを決めなければなりません。
以前、 The little book of Buster.JS という電子書籍を書いた際は、 Sphinx(reStructuredText)を使って書いていたため、今回は別の方法を取ってみようと考えました。
最初に候補にあげたのは人気のあるMarkdownでした。 しかし、Markdownには外部ファイルを読み込んで埋め込む標準的な方法がありません。
The little book of Buster.JS を書いた時からサンプルコードにテストを書くことにしていたので、 外部ファイルを読み込む機能は必要なものでした。
拡張したMarkdownフォーマットを利用するのも良いですが、その時にAsciiDocというOreillyも使っているフォーマットがあることを思い出しました。 また、Asciidocのモダンな処理エンジンとして Asciidoctor という実装があることを知り、 これを使ってみようと思いました。
まとめると、主目的は電子書籍を書いてみたいという欲求で、サブ目的がES6 Promisesについて扱いきれなかったものを書く というのがこの書籍を書き始めた理由です。
おおまかに書く内容と形式を決めましたが、 私は形から入るタイプなので、Asciidocで書くときにどのようなプロジェクト構造が良いのか悩んでいた記憶があります。
そのため、一番最初に書いたのは CONTRIBUTE.md で、 コントリビュートガイドを書くという形でプロジェクトの構造がどうあるべきかについて決めていきました。
書籍の内容としては、Promiseの基本的な使い方、パターンをコード例中心に書いていくというおおまかな方針が決まっていたので、 それをより明確にするためにアウトラインを固めていきました。
アウトラインを固めつつ、書籍を書く上で一番コワかったのが飽きることだったので、 とりあえずでもいいから気になったことについてをセクションに分けて書いていきました。
そのため、書いた順番はかなりバラバラで、第二章や第四章を最初の頃に書いていました。
多くのセクションは、最初にコンセプトとなるサンプルコードとテストを書いて、 それに対する解説として文章を書いていくという方針で行っていたものが多かったと記憶しています。
そのため、いいサンプルコードが思いつかないセクションは後回しにする傾向がありました。
飽きる前に一度完成の形まで持っていきたいという気持ちがあったため、 とりあえずの目標として三ヶ月でひとまずの完成まで持っていくとしていました。
この書籍以外にもやりたいことは山ほどあるので、 どう目標を達成するか考える前に、空いてる時間を使っていくしかないという感じがしてました。
空いてる時間として一番ありそうなのは移動中の時間でした。
移動中でもMacBook Proの上にThinkPad Bluetooth keyboardを載せて使えば、 普段とあまり変わらないレベルで書けることがわかったので、移動中にコーディングや文章を書き進めていきました。
もちろん、この文章も移動中に書いてます。
移動中に書く短所としては、電波があまり強くないのでオフライン環境になってしまうケースがあることでした。 そのため、移動する前に移動中に何を書くのかを計画してから進める癖が自然とついた気がします。
その影響はGitHub Issueの使い方に強く出ていたと思います。
実際にセクションを書く前に、GitHub Issueにそれぞれのセクションでやりたいことや、 コンセプトとなるサンプルコードのアイデアを大量にメモるようにしていました。
メモやアイデアを元に、移動中に実装などを進めることで結構集中してできたと思います。
それぞれのセクションはGitのブランチを切って進めて、[WIP] のpull-requestを出した状態で進めていました。
WIP のpull-requestを作って置くことで、
どこまで進めたのかや別のアイデアが思いついた時は書くことができるため、
書いてる文章やコードに対する意見等も記録して残しやすくなりました。
一度の移動中でセクションが完成することは少ないので、 どこまでやったかを簡単に見られるようにすることは結構大事でした。
2014年3月2日に書き始めて、2014年6月2日に全ての章が書き終わり、リファクタリングに入ったので、 大体目標を達成できたように思えます。
先ほども書いたように、WIP pull-requestを使ったワークフローを取っていましたが、 最初からこのワークフローで書いていた訳ではありません。
最初の頃はGitHub Issueにアイデアをメモるだけで、殆どmasterブランチで作業していましたが、 第四章の応用の内容を書いていくあたりからワークフローが変わってきました。
この書籍の第四章では、第二章の基礎を発展させた応用的な使い方について書いています。 しかし、それまで好き勝手書いていたため、応用するにも基礎の部分の説明をまだ書いてないというセクションがでてきました。
セクション毎にIssueは立てていたので、どのIssue同士が関係あるのかをIssue References(Issue番号書くだけ) で整理したり、文章全体としての流れを汲み取っていく必要が出てきました。
大抵は一つのセクションが一つのIssueと対応していたので、 作業も一つのセクションと一つのpull-requestを対応させて行った方が管理しやすいと気付きました。
これが自分自身にWIP pull-requestをするようになった理由だと思います。
|
Note
|
GitHub Issueを使った執筆のワークフローについては 一人で使えるGithub Issue にまとめています。 |
物理的な書籍と違っていつでも更新出来るとはいえ、 最低限おかしなところは直さないと行けないため、文章をひと通り書き終わってから誤字などチェックを始めました。
また、最初に好き勝手書いてた影響もあり、セクションの順番を変えたほうが良い箇所もあるなど、 全体的な流れを直す作業もレビューと一緒にやっていました。
全体的な流れを見るために、あるセクションがどのセクションに依存してるか、 逆にどのセクションから参照されてるかを見るためのツールを書いて、依存関係がおかしくないかを確認していきました。
この影響で第二章のセクションの一部が第四章に移動したものもあり、 第二章はPromiseのメソッドの解説に集中した感じに変わったと思います。
誤字脱字などは @vzvu3k6k さんにたくさんのpull-requestを送ってもらったり、 自分もiPhone等のモバイル端末から直接GitHub Issueを立てられるようにして一文字のtypoのIssue等を大量に立ててチェックしていきました。
HTMLで見られるようにするとモバイルでも十分文章のレビューは出来るので、 作っておいたIssueをTiDD(チケット駆動開発)の要領で処理していくと文章の修正もテンポよく進められました。
ここでもGitHub Issueを活用していましたが、typoのような小さな修正と新規セクションを書くような大きな変更では、 使い方の違いがでてきた気がします。
どちらもブランチを切ってコミットする所までは同じですが、
小さな修正はコミットメッセージに fix #108 というように書いてマージするだけで、わざわざpull-requestはしてませんでした。
|
Note
|
コミットメッセージのルールは Angular.jsで使われている Git Commit Guidelines をベースにしています |
逆に大きな修正はpull-requestを使って進めることで、 マージする前にもう一度確認しやすかったりやTravis CIによる自動テストが走るため、 ミスが減った気がします。
一人で書いてる書籍だったので、 機械的にチェック出来るところを出来るだけ多くして間違いを減らそうとしていました。 自分自身にpull-requestsを送るやり方は機械的なチェックを挟みやすかったので、 このワークフローを体感出来たのは良かったと思います。
しかし、レビュー時に立ったIssueの7割ぐらいは日本語的な問題だったので、日本語は難しいなーと思いました。