読者です 読者をやめる 読者になる 読者になる

プログラマでありたい

おっさんになっても、プログラマでありつづけたい

「Amazon Web Services パターン別構築・運用ガイド」の執筆環境

Amazon Web Services パターン別構築・運用ガイド

Amazon Web Services パターン別構築・運用ガイド

 今回の「Amazon Web Services パターン別構築・運用ガイド」は、会社の同僚たち4人で書き上げました。会社の同僚といっても、東京と大阪に別れていたり、日中に打ち合わせをする時間もないので、ほぼリモートのやり取りだけで完結させました。かなりスムーズにいったのですが、幾つか課題もあるので、忘れないうちにメモです。

執筆を支えるシステムの全体像



 リモートでやり取りをする為に、幾つかのツールを組み合わせて簡単な環境を作りました。方針としては、執筆に集中するために出来るだけSaaSを利用し、余計な時間を取られないようにしました。まずは全体像を見てください。

f:id:dkfj:20150321001245j:plain

 GitHubを中心にシステムを構築しています。

目次と担当割りを管理するGoogleスプレッドシート



 まず目次や担当割りなどは、Googleのスプレッドシートを利用しました。最初にテーマや想定の読者層を設定し、その上で大きく章割りをしました。そして、節単位で各テーマを配置し、さらに分解していくという作業をしています。そして、担当を決めました。今回は、アプリが得意な人間、ミドルが得意な人間、インフラ・運用が得意な人間と上手いことバラけていたので、担当もスムーズに決まりました。

システムの要、GitHub



 次にシステムの要であるGitHubです。とりあえずこれがあれば何とかなるというレベルで重宝していました。執筆のプラットフォームとしてGitHubの良い所は、MarkDownで書いておくと、そのままWebでほぼ誌面の形で見られるということです。これがために、MarkDownを使っているのかもしれません。あと、レビューの指摘事項にはIssueを使うと便利です。
※後述しますが、レビューの問題点はありました。
 今回は、節単位(3章の1とか)で分割しているので、基本的にはPush時にコンフリクトは発生することはありません。しかし、基本的には各自ブランチを作ってマージするという形でやっていました。ブランチの単位は節単位でしたが、1週間サイクルで動いてたので週単位のブランチになることもありました。いずれにせよ、執筆する際は、1週間単位で動くのがちょうど良さ気です。

CircleCIで継続的にドキュメントのビルド



 GitHubにPushすると、連携したCircleCIでPandocを使ってビルドするように設定していました。前回の反省で、MarkDownからの変換環境をローカルに持つと、他の端末で作業するときに面倒臭いという事態を避けるためです。特に今回は複数人なので、必須と考えていました。結果的には、このPandocでのビルド結果は、あまり重要にはなりませんでした。理由としては、後述のAtomです。

プレビュー付きのテキストエディタ Atom



 Atomはテキストエディタです。全員が使っていた訳ではないのですが、かなり重宝しました。何が便利かというと、MarkDownのプレビュー機能があることです。しかもリアルタイムに反映されます。執筆していると、ついつい文字ばかり書いてしまって、読むのを躊躇するくらいギッシリとしたページになってしまいます。プレビューをしながら書くと、文字が多くなってきたので画像や表、ソースを入れて調整しやすくなります。執筆時には、下記のスクリーンショットのようにプレビューしながら書くことが多かったです。

f:id:dkfj:20150321003055p:plain

 個人的には、Atomのプレビューに満足して、CircleCIのビルドしたPDFの精度を上げなかったのが少し失敗だったと思います。

連絡には、Gitter



 チャットツールとしては、Gitterを利用しました。GitHubの連携性に優れているというのが理由です。実際のところ、GitHubに連携することも少なかったので、ChatWorkやSlackでも良かったでしょう。ただ、Gitterも中々使いやすかったです。

課題



 執筆中は上記の構成で、全く問題は発生しませんでした。しかし、編集者との校正が始まると、一転して混乱が生じました。理由としては、校正にMSのワードやPDFを利用するようになるからです。そうなると、今まで活躍してきたGitHubは、単なるファイル置き場になってしまいます。編集者からのフィードバックのフォルダや、そのフィードバックに対する修正フォルダといった感じですね。ちょっと悲しいですね。
 対策としては、紙やPDFが出てくる最終校正の前までは、MarkDownのテキストファイルでやり取りできるようにすることです。その為には、CircleCIで作ったドキュメントの精度を上げて、かつビルド後の配布方法をメールやDropBoxなど、もっと直接的なものにすべきだったと思います。

課題その2



 ビルドしたドキュメントの精度ですが、これは如何に紙の誌面と同じように見せるかという点です。この点、MarkDownの記法での表現力は、正直物足りません。画像のサイズの指定であったり、コラムや注釈の書き方などに限界があります。もう少し表現力が高いものとしては、ReVIEWがあります。今回、どちらを採用するか悩んだのですが、フォーマットの普及率から考えて、MarkDownを採用しました。恐らく今後もそうなるでしょう。
 では、表現力の不足をどう補うか。まだ検討段階ですが、CSSを試してみようと考えています。素の文章を書いたMarkDownと、それに対となるCSS、またベースとなるCSSを用意します。そしてビルドサーバで、両者を合わせたドキュメントを生成すれば、うまくいくのではと妄想しています。この辺りは、今後試してみます。実際の電子化の工程の話を聞いてみたり、Kindleの書籍化をしている人の話を聞いてみたいですね。

まとめ



 執筆時にバージョン管理システムを使うのは、もう当たり前です。今は、原稿をいかにビルドするか。その段階に入っているのではと思います。理想は、すぐにKindleで出版できるレベルですね。

See Also:
「Amazon Web Services パターン別構築・運用ガイド」の目次
AWSパターン別本の狙い。例えばAutoScalingを使えるように。「Amazon Web Services パターン別構築・運用ガイド」の裏話
『Amazon Web Services パターン別構築・運用ガイド』を書きました
『Rubyによるクローラー開発技法』を書きました
本を書く前に準備したこと、執筆中にしていたこと

Amazon Web Services パターン別構築・運用ガイド

Amazon Web Services パターン別構築・運用ガイド