Sphinx本の執筆体制について¶
この記事は ドキュメンテーション Advent Calendar 2013 の4日目の記事です。
すでにかなり時間がたってしまっておりますが、2013年9月に Sphinxをはじめよう という電子書籍をO'reilly Japan様から出版させていただきました。
もちろんSphinxで執筆しました。ここでは、その際に分かったtipsなどを共 有したいと思います。
のはずだったのですが、特別なことはなにもなく、普通にSphinxで書くだけで したので、Tipsというものはほぼありませんでした。(Sphinx後のフォント周り などでいろいろ問題があったようですが)
そのため、今回はどういう体制で執筆したかについて説明したいと思います。
1. 執筆体制¶
4人で執筆しました。
基本的に一人一章ずつ、それに加えて付録を適当に割り振って執筆していきま した。
2. Bitbucket¶
Sphinxですので、原稿はすべてテキストファイルです。これを Bitbucket のプライベートリポジトリに置きました。
Bitbucketはプライベートリポジトリが無制限に置けるので非常に便利です。た だ、多人数で使うとお金がかかってくる場合があるのでそこは注意が必要です。 お金を払いましょう。
文字単位の差分diff表示¶
文章ですと一文が長くなり、通常の差分表示ツールだと一文のうちのどこが差 分か分からなくなります。しかし、Bitbucketの差分表示は文字単位でハイライ ト表示してくれるので、どこが更新されたかが一目で分かりとても追いやすかっ たです。
ブランチ戦略¶
一章ずつで手分けをしているので衝突が生じることはあんまりありませんし、 3 way mergeでほとんど解決します。最後までブランチを分けることはありませ んでした。
ちなみにcommit数は500以上でした。
3. Issue Tracker¶
課題管理ツールとして、
bitbucketのissue tracker
sphinxのTODO拡張
の両方を使っていました。
SphinxのTODO拡張は ..todo:: と書くだけで、あとは先頭ページに書いた ..todolist:: に列挙されるので、執筆序盤の「とりあえず考えを書き出した い」という時にとても有用でした。
Bitbucketのissue trackerの方は、主にレビューと議論に使っていました。議 論とは、例えば複数人で執筆している時に出てくる「用語の定義」などです。 訳語をどうするかなど意識が異なっている部分もあり、そういうときの議論に Issue Trackerを使っていました。
4. Jenkins¶
@tk0miya さんが立ててくれました。BitbucketにプッシュするとJenkinsに通知 が行き、JenkinsがSphinxを起動してHTMLとPDFを自動的に生成してくれます。 もちろん失敗した場合にはそのような通知が飛んできます。
各自のPDF環境を揃えるのは意外と面倒なので、Jenkinsで常に最新版のPDFが手 に入るというのは有効でした。
5. Skype¶
実際の細かなやり取りにはSkypeのグループチャットを使っていました。その場 にいなくてもあとから見れるので、「この部分やります」などと書いておくと あとから見た人が分かる、という非リアルタイムのチャットツールとして便利 でした。
ぼく以外の人は土曜日などに実際に集まって執筆していましたが、ぼく自身は 結局今日最後まで集まることは出ませんでした。それでもそこまで苦労したと いう印象はありません(他の人が苦労したかもしれませんが…)
ただ、議論がSkypeとBitbucketのIssue Trackerとに分散してしまい、あとから 追えなくなってしまった、ということが数回起きました。これは課題ですね。 Hipchatを使えば連携できるんでしょうか。
6. Google Spread Sheet¶
レビュアーとしてたくさんの方が関わってくださいました。大変感謝しており ます。
Google Spread Sheetに各章ごとのシートを作成し、そこにコメントを書き込ん でもらうようにしました。Google Spread Sheetは複数人が同時に編集できるの で多くの方が書き込んでも問題が生じませんでした。
また「反映済み」の行の色を変えることで、どれぐらい残っているかが分かりました。
BitbucketはPrivateにしていたので、Issue Trackerは使えませんでした。
まとめ¶
Sphinx本を執筆した時のツール群とそれらを使う体制についてまとめてみまし た。
本を執筆するのは始めて、かつ、複数人での作業でしたが、これらのツールを 駆使することで、特に問題なく執筆ができました。文章以外は、ですが…
最後になりましたが、レビューしていただいた多くの方、そして執筆の機会を くださったオライリー・ジャパンの瀧澤さんに感謝いたします。
Comments
comments powered by Disqus