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

C++ポケットリファレンスについて書ききれなかった、いくつかのこと

C++ Book

昨日、『C++ポケットリファレンス』の紹介エントリを書きましたが、ここではそのエントリで書ききれなかったことを書きます。読者向けではなく、この本の著者とレビュアーのためにプロジェクトの記録として残すことと、本の執筆に携わる人に参考にしてほしい、という意図で書きます。


プロジェクトメンバの構成
C++ポケットリファレンス』の執筆は、6人の共著者、編集者が1人と、5人のレビュアーが関わっています。ぼくはとりまとめ役です。
その内、レビュアーの一人である兎さんが、レビュー管理のためのRedmineを立てて運営してくれていて、同様にレビュアーの一人であるDigitalGhostさんが、原稿管理のためのGitリポジトリを用意してくれました。Gitリポジトリは、弊社ロングゲートのサーバーに置いてあります。


使用したサービスとツール
単著でレビュアーなしであれば、エディタで原稿を書き、それを編集者に送って小さなやりとりをすれば済みます。しかし今回はレビュアーが常時議論に参加する体制でかつ、共著者同士で頻繁に意見合わせする必要があったので、議論する場所やサービスを、しっかり選ぶ必要がありました。

  • co-meeting

co-meetingは、Google Waveから引き継いだ、メールとチャット、Wikiのいいとこ取りをした、議論をするのに特化したサービスです。リアルタイムなやりとりができる関係で、メールのように「こんにちは、高橋です。 ... 以上です。」みたいな挨拶文を毎回書こうという考えが起こりにくいので、気軽な書き込みができます。以前私が関わった書籍では、同じようなメンバでメーリングリストを使用していましたが、書き込みの量が全然違いました。クイックレスポンスを期待できるサービスを使うと、議論が促進される、というのがよくわかりました。
一度発言した内容をあとから編集できるのと、個々の発言に、間に返信ができるのも重要なポイントです。チャットのように「あの話どうなりましたっけ?」と話題が流れて or 分散してしまうことを防げます。もちろん未読管理もあります。
議論をする流れとは別に、議論のまとめとなるWikiが同画面に用意されてるので、話がまとまったことを都度まとめていくことで、どの議論がどうなったかを追いやすくできます。
co-meetingのグループには、技術評論社の編集さんも常時参加していて、こまめにアドバイスをもらっていました。

厳密にはRedmineから分裂したChiliProjectというツールなのですが、プログラマならおなじみの、バグ管理システム(BTS)です(以下、めんどくさいのでRedmineと言うことにします)。私が関わる書籍では、『C++テンプレートテクニック』の頃からレビューのためにバグ管理システムを使っています。レビューは小さい単位でチケットとして発行され、はじめは担当章ごとに自動的に担当が割り振られます。
担当と、チケットを発行した人だけで議論が解決しにくい場合には、co-meetingにチケットへのリンクを貼り、そちらでみんなで議論しました。co-meetingに議論が移行したら、チケットの方には、co-meetingでの議論へのリンクを貼り、議論が行方不明にならないようにしました。もちろん、チケット上でみんなを呼んで議論することもありましたが、やはりco-meetingに持っていった方が議論がよく進みました。
ぼくは取りまとめ役だったので、全てのチケットの通知を受け取るようにしていました。
ちなみに、一番多かったチケットは、著者間でスタイルが統一されていないことの、個別指摘でした。

  • Git

Gitは、これまたプログラマならおなじみの、バージョン管理システム(VCS)です。原稿はプレーンテキストの、独自のWikiっぽい記法だったので、Gitで管理しやすかったです。『C++ポケットリファレンス』は共著で、かつぼくが「著者は全員、全ての原稿に責任持てるようになってください」とくどくど言ってた関係で、全員が全ての章にコミットするので、差分を追いやすいことは重要でした。
Gitだから困ったことは、ローカルコミットをして、なかなかサーバーにpushしてくれない人がいた、くらいですね。


たたき台
共著でスタイルを合わせていくタイプの本だったので、執筆スタイルを統一する必要がありました。なので、最初に数名に「たたき台となる原稿を2〜3個書いてください」と依頼しました。それを著者とレビュアーでレビューし、ある程度の執筆スタイルをそこで確定させました。
ただし、この時点で「もしこんなケースが発生したら」みたいな、まだ起こっていない問題については、深く詰めることはしませんでした。最初からあまりガチガチに規約でしばると、執筆しにくいと考えたからです。


マイルストーン
短期的な目標を立てないままダラダラ進めるといつまでも終わらないので、最初に編集さんと会った時点で、マイルストーンを提出しました。「たたき台」の執筆とレビュー、各自が1章ずつ書き終わる、各章の個別レビュー、総合レビュー、追加執筆が必要なものの締め切り、といった感じで、小さな目標とスケジュールを立てました。
ただし、これはそれほどうまくいきませんでした。本来のスケジュールであれば、2012年11月にはリリースされていたはずが、2013年5月まで延びました。これは、私の管理力不足で、たとえば「著者が1章書き終わるまでひたすら待つ」というようなことをしていたからです。ちょくちょく、「どういう状況?」という程度の確認はしていましたが、どんなに小さくてもこの日に必ずコミットしよう、みたいな中間成果物の提出を義務付けたりしていれば、もっと違ったかなと反省しています。みんな副業でやっているので、ある程度は仕方ないですが、ずるずる行き過ぎた部分はたしかにありました。


議論の分け方
またco-meetingに戻りますが、co-meetingでは、議題ごとにディスカッション場所を分けることができるので、どんな議論を立てるかも、わりと重要だと思います。『C++ポケットリファレンス』では、以下の議論が立てられました。カッコ内は発言数です。

  1. はじめに(73)
  2. 雑談(427)
  3. 雑談2(231)
  4. 相談ごと(649)
  5. 相談ごと2(532)
  6. 執筆状況(422)
  7. レビュー依頼(397)
  8. お知らせ(99)
  9. 目次を考える(374)
  10. 担当者を考える(11)
  11. たたき台の執筆とレビュー(74)
  12. 執筆スタイルを考える(216)
  13. コーディングスタイルを考える(124)
  14. 表記の目安(171)
  15. cpprefjpを書く(16)
  16. 原稿ファイルの命名を考える(22)
  17. 付録を考える(114)
  18. どこかで定義したほうがいい用語(48)
  19. 扱わないものリスト(11)
  20. ハッカソン(95)
  21. イテレータ無効化について(49)
  22. 出典を記載する(10)
  23. 計算量をまとめる(319)
  24. 「はじめに」を書く(39)
  25. 「謝辞」を書く(16)
  26. 本文デザイン(9)
  27. カバーデザイン(145)
  28. 組版・校正(586)
  29. 索引を作る(26)
  30. 著者プロフィール(27)
  31. マーケティング(44)
  32. Boost.勉強会(17)

Redmineでのやりとりを含めずに、co-meetingだけで実に4,793回のやりとりが行われたということになります。
議題の全てを一つひとつは説明しません。タイトルからなんとなく想像してください。「はじめに」は、このプロジェクトに参加するときに最初に見るべき場所で、リポジトリRedmine等への各種リンクや、この本の目的などの議論を行なっていました。「雑談」は、プロジェクトと直接関係ない話題。プロジェクトのことしか話せないと議論が失速してしまうんじゃないかと思い、用意しました。「相談ごと」は、プロジェクトに直接関係する、チケットを起こすほどでもない小さな議論、もしくはチケットで込み入った議論になった場合の議論場所として使いました。


ハッカソン
全員が1章ずつ書き終わった段階から、2週間に一度、集まれる人で集まってオフラインで議論しながら執筆&指摘修正をしていました。ハッカソンというより、スプリントと言った方がよかったかもしれません。hotさんだけは、札幌在住なので、オフラインの議論にオンラインで参加していました。オフラインで出た議論はできる限り、リアルタイムにco-meetingに同期し、参加できなかった人も議論の内容を知ることができるようにしてました。
ハッカソンの場所は、下北沢にあるオープンソースCafeというところです。丸一日いて1,000円で、何かタスクを消化すると飲み物が安くなり、無線LANが常備されていて、かつプログラマが集まるのでそれなりに静かです。子供プログラミング道場とかもやっていて、なかなか楽しいです。


以上が、『C++ポケットリファレンス』プロジェクトの、私の記録です。誰かのなんらかの参考になれば幸いです。