このエントリーをはてなブックマークに追加

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本を執筆した時のツール群とそれらを使う体制についてまとめてみました。

本を執筆するのは始めて、かつ、複数人での作業でしたが、これらのツールを駆使することで、特に問題なく執筆ができました。文章以外は、ですが…

最後になりましたが、レビューしていただいた多くの方、そして執筆の機会をくださったオライリー・ジャパンの瀧澤さんに感謝いたします。