技術書のレビューの経験則

出版される前の本の内容は、通常は著者や編集者に代表される「制作サイド」の人間にしか読まれない。 専門性の高い本であれば査読とか監修といったプロセスを有識者にお願いすることはあるけど、そうしたお願いをするときには有償だったりカバーや袖に名前を出したりすることが多いので、これも「制作サイド」の一部とみなしていいだろう。

一方、基本的に無償で、完成した書籍の献本と謝辞への掲載くらいを前提に、あくまでもベストエフォートで発行前の本の内容を見てくださいというお願いを第三者にすることもある。 この場合の第三者というのは、制作中の書籍の想定読者だったり、出版後の書籍を対象読者へ紹介してくれそうな立場の人だったりする。 このようなプロセスを制作に取り入れる習慣は、とくにここ数年のIT系の出版社ではめずらしくなくて、界隈では「レビュー」などと呼ばれている。

というわけで、技術書の制作における「レビュー」について、自分の経験をもとに知見を整理しておきたい。 自分の経験をもとにはしているけど、たぶん日本で技術書のレビューをまわしてきた経験数では上位にいるはずなので、独りよがりではあるかもだけど意味がなくはないはず。

余談だけど、たぶんこういう出版前の状態を有志にボランティアでレビューしてもらうという文化を技術書界隈で積極的に始めたのはアスキーなんじゃないかなと思う。 少なくともぼくが最初にこういうプロセスの存在を知ったのは、アスキーの256本とかで執筆兼レビューのためにメーリングリストを使っているのを見たときだった。 彼らがどこまで意識的にこれをプロセス化していたのかは知らないけれど、この記事は、彼らがやっていたプロセスをぼくの前職のチームの先輩だった森田さんが取り込み、いろいろな著者、訳者に協力してもらいながら発達させてきた手法がベースになっている。

技術書のレビューのパターン

まず、レビューと一口にいっても王道のプロセスがあるわけではなくて、依頼方法およびレビュアーどうしのインタラクションの有無によっていくつかの形に分類できる。

	レビュー内容は制作サイドだけが見たい	レビュー内容が他のレビュアーにも見えてよい
制作サイドで知己がある人に依頼	①	②
制作サイドで知己がない人に依頼	③	④
不特定多数	⑤	⑥

上記の表のいずれのパターンに該当するかによって、レビューの具体的な手法やツールがだいたい決まる。

技術書のレビューの手法

とはいえ、実際にはレビューの具体的な手法やツールがまずあり、その結果として上記の表のいずれかに当てはまるという状況が多いだろう。 いずれにしても、誰にどういう方法でレビューをしてもらうかは、レビューに使うツールやプロセスに依存する。 そこで、次はツールという観点から上記の表の各セルとの適正について整理してみよう。

バグトラッキングシステムを利用する方法

②と④の場合は、プライベートなバグトラッキングシステムを使うことが多い。自分がかかわるプロジェクトだと、一昔前はTracのチケット、いまではGitHubのissueとしてフィードバックをもらっている。 もちろん、TracやGitHubなどのシステム側で不特定多数の参加を許可するようにすれば、⑥の場合にも使える。

バグトラッキングシステムを使うメリットとしては、あるレビュアーが見つけた問題を制作サイドやレビュー陣営全体で共有しやすいことが挙げられる。原稿のバージョン管理をしている場合にはリポジトリに関連付けられたバグトラッキングシステムを使えるので、フィードバックへの対応履歴を管理しやすいというのも魅力。ひとことでいえば、レビュアーとレビューを受ける側のトータルでの負担が最小化される方法だといえる。

レビュアーどうしでチケットやissueで議論ができるので、著者や編集者だけ、つまり制作サイドだけでは思いつかないような解決策が出たり、特定のレビュアーの偏った意見なのかそうでないのかを客観的に判断する材料ができたりするというメリットもある。

デメリットは、レビュアーが見つけた問題をチケットやissueにするときに、指摘したい場所を一意に伝えにくいこと。ほとんどの場合、レビュアーが見る対象というのは、原稿ソースに技術的にアクセスができる場合でも、組版されたPDFである。そのため、一般には「mページのk行め」のような指示方法になるしかないのだけれど、これには次の難点がある。

• レビューを受け取る側ではPDFでなく原稿ソースのほうを見ているので、「mページのk行め」という情報は使わず、指摘内容からキーワードをgrepして該当箇所を探している。つまり、「mページのk行め」まで粒度が細かい情報は無駄になってしまうことが多い。原稿ソースが頻繁に更新される環境だと、レビュー対象のPDFと制作進行中のPDFとで場所の乖離がさらに激しくなる
• 「mページのk行め」のような指摘は、他のレビュアーにとっても優しくないので、指摘のダブりが意外と発生しやすい。ダブりを防ぐために修正ずみの問題をすぐにクローズしないといった運用をしても、なおダブる。そもそも修正ずみの問題をクローズできないのでは、バグトラッキングシステムを使う利点が半減してしまう

場所の指示がめんどうであることに加えて、バグトラッキングシステムを利用することには、レビュアーが他のレビュアーの意見を読めてしまうことによるデメリットもある。

• うまく回ればレビュアーどうしの議論によって問題の文脈がはっきりするのだが、ときには議論の発散という形でデメリットになる場合もある
• 声が大きい有名人がレビュアーにいることで他のレビュアーが委縮してしまい指摘しづらい雰囲気ができたり、そのようなレビュアーの意見に流される可能性がある

まとめると、バグトラッキングシステムを使った技術書のレビューには、手軽に問題を管理できる一方で、指摘箇所を一意に特定するのが困難であり、他のレビュアーとのインタラクションが不可避であるというデメリットがある。 そのため、冒頭の表における②のような著者や編集者が議論をコントロールしやすいレビュアーの集合である場合に向いた手法だといえる。 ④の場合には、レビューの要件を具体的に明文化しておく必要があるだろう（もちろん②のケースでも明文化したほうがいいんだろうけど）。 一方、レビュアーが他のレビュアーの意見によってバイアスを受けるのを避けたい場合（①、③、⑤）、自転車小屋の屋根の色をめぐる議論に巻き込まれたくないという場合（⑥）には、使えない。

問題点を個別に直接送ってもらう方法

複数のレビュアーがバグトラッキングシステムで相互に意見を交わしながら技術書のクオリティを上げていく作業は、うまく回ると本当に楽しい。それ自体がエンターテインメントだったと感じることも少なくない。 しかし、そういう場が醸成されるまでには時間がかかるし、そもそも成功するとは限らない。オープンソースプロジェクトに慣れている著者かどうかという文化的な違いによる困難もある。 前述したように、レビュアーが他のレビュアーの意見によってバイアスを受けることを避けたい場合もある。

そこで、著者 and/or 編集者が個別にレビューを依頼し、一対一でフィードバックを返してもらうというケースもかなり多い。 その場合には、メールで指摘をもらったり、PDFのコメント機能を使ってもらったり、最近だとDropboxのコメント機能を使うこともある（Google Driveにも同様の機能はあるので使えるかもしれない）。

この方法は、フィードバックをもらうという一点に特化すればもっとも優れている。 Acrobatのレビュー機能やDropboxのコメント機能を使えば、バグトラッキングシステムでは不可避だった指摘箇所を一意に特定する難しさがある程度は解消できるという利点もある。

難しいのは、なんといっても人選。 バグトラッキングシステムを利用すれば十数人規模になってもハンドリング可能だけど、個別にやり取りをする負荷を考えると、数人に抑えたいところ。となると、ピンポイントで適切な人に依頼するのが現実的だといえるだろう。 そういうわけで、冒頭の表における①や③に向いた方法だといえる。 ⑤でも使えなくはないけれど、というか⑤をやりたいときはこの方法しかないんだけど、制作サイドが個別のやり取りの負荷を覚悟する必要がある。

クラウド上で共有したPDFにコメントを付けてもらう方法

DropboxにPDFを置くと、閲覧できる人が誰でも文字列をハイライトしてコメントをつけられるようになる。 この機能は、個別に指摘をもらう場合だけでなく、複数のレビュアーから同時に指摘を受ける場合にも使える。 Dropboxによる方法のメリットは、実施前の手間が最小であること。なにしろ、Dropboxに置いてリンクを伝えるだけでいい。 モダンブラウザがあれば説明不要で直観的に指摘箇所を一意に特定できるのもお手軽さにつながる。

デメリットは、DropboxのPDFビューアーはPDFの仕様に準拠していない独自の拡張で、次のような不自由があること。

• 書籍全体の検索ができない場合がある。検索対象になるのはブラウザが描画ツリーを構築した部分だけ
• コメントのステータスが未解決と解決済みの2つしかないので、複数のレビュアーからの指摘がダブらないようにするにはすべて未解決にしておくしかない。そのため、レビューを締め切るまで取り込み作業がしにくい
• 個々のコメントにURLが付かないので、議論が始まったコメントや見逃したコメントを通知をたどって追いかけるしかない
• PDFデータにはコメントが埋め込まれないので、ダウンロードしてPDFリーダーでコメントを管理することも、PDFデータからコメントを抜き出すこともできない

このような制約があるので、DropboxでPDFにコメントをもらう方法をうまくまわすには、PDFのページ範囲を小さく章単位などに絞ったり、レビューの締め切りまではコメントを解決済みステータスにしないようにしたり、少し工夫がいる。 それでも、指摘箇所を一意に特定しやすいというメリットは大きいので、Slackなどの他メディアでレビュアーと制作サイドが気軽に議論ができる②のような状況であれば、かなり魅力的だと思う。

もうひとつ、Dropboxに代表される共有PDFへのコメント書き込みには、指摘がミクロに偏りがちになってしまうという見過ごせない欠点がある。 この欠点を補うにも、レビュアーと制作サイドとが雑談できる場の用意が重要な気がしている。

なお、この方法で技術書のレビューが可能なのはDropboxだけではない。 Google Docsにも指摘が行単位になるけど同様の機能はあるし、Adobe Readerにも共有レビューという機能がある。 PDFの仕様にそったアノテーション機能であるAdobe Readerの共有レビューが使えるのがベストなんだけど、Adobe ReaderがLinuxベースの環境で事実上使えなかったり、macOSでもインストールしてない人がいたりするから、つらい。

技術書のレビューをする側の心得

ここまでは、技術書のレビューを受ける側に向けた話だった。 ここでは、レビューをするときにどんなことを意識したらいいかについてざっくり書いてみる。 ただし、ぼく自身はレビューを受ける側の立場に立つことが多いので、主にレビューを受ける側の視点が多分に混ざります。

レビューでがんばって探しちゃだめな問題

レビューで何を見るべきかを要約するのは難しいけど、がんばって見てはいけない問題というのはある。 建前としては「気づいたことを何でも指摘してほしい」なんだけど、何に気付くかは「何に気付こうと思って読んでいるか」に多分に影響されるので、「この点については意識的に探す必要がない」を意識するのはけっこう重要。

• 誤字脱字など、日本語上のミス
• 漢字や送り仮名などの表記ゆれ
• レイアウトの不備

これらは、「気づいたなら指摘しておく」という態度で読めば十分で、レビューというプロセスでがんばって探すべき問題ではない。 逆に言うと、制作サイドの心得として、これらの問題をなるべくつぶした状態でレビューを開始すべきともいえる。

なんだけど、時間的な制約もあるので、現実にはそうでない原稿をレビューすることになる機会もある。 そういう問題が多く残っている状態でレビューをすることになった場合には、上記のような問題を一生懸命に探してあげるのではなく、「この章は誤字脱字が目立つけどあとで修正されるのですよね？」といった大局的なコメントを残すのがよい。 技術書のレビューの主眼は、あくまでも第三者の目を取り入れることであり、校正作業のボランティアではないのだから。

レイアウトについても同様で、完成途中のPDFを見るとどうしてもアラが目立つけど、それはやはりレビュアーが気を配る部分ではない。 「レイアウトの不備で有意義なレビューが困難である」といった指摘に留めよう。

ミクロな指摘より、マクロな指摘を

誤字やレイアウトの不備にも関係するけれど、第三者であるレビュアーがミクロに指摘したくなるような原稿の問題は、もっと広いスコープでの問題という場合が少なくない。 なんか日本語がわかりにくいなあと思って、語の位置を変えたり読点を追加したりしたミクロな修正案を出すのは、実は解決になっていないことが多い。 レビュアーがミクロな指摘で解消を試みた問題の根本的な原因は、より広いスコープで原稿の問題を解消できる人、つまり制作サイドでないと対処できないことが多い。

レビュアーとしては、なんか日本語がわかりにくいなあと感じる箇所があったら、「〇〇ということが言いたいんだと思うんだけど、なんか日本語がわかりにくいなあ」と指摘するのがベター。 〇〇すらわからないなら、「文意が不明」といったコメントでも十分。

自分にとって理想的な本にする機会ではない

技術書のレビューは、校正作業のボランティア募集にならないためにも、制作プロセスではかなり後の工程になる。 つまり、レビュアーとしては、本のコンセプトや表現方法、近日中の出版については了解しているということが前提になる。 したがって、内容に間違いがあると考えられるなら指摘すべきだけど、本の表現に対して調整を要求する場ではないという自覚は必要である。

文章に対するレビューというのは、センシティブなプロセスだ。指摘者以外にとってどちらでもいい話であることも少なくない。 どちらでもいい話に「どちらでもいい」というのは精神力がいるものなので、はじめから不採用前提くらいの気持ちだとみんなが楽になる。 たとえば、同じ内容ならこっちを説明すべきとか、説明の日本語表現はこっちのほうがいいとか、そういう指摘についての最終的な決定権は制作サイドにゆだねる。 制作サイドもまじえて議論になり、最終的な文章表現をなにか決定しないといけなくなったところで、代替案の作文をするくらいが双方の負担にならず、ちょうどいい。

逆に、著者や編集者には、無慈悲な独裁者となる覚悟が必要だといえる。 そういう意味ではオープンソースのコミッターと同じなのかも。 報われないかもしれない指摘であるという点について双方が納得していないと、レビューは回らない。

実践例

いままさに進行中の本の大規模レビューは、冒頭の表だと④、もしくは⑥に近いプロジェクトである。 そこで、指摘箇所を一意に特定する部分の困難さを回避しつつ、指摘の重複回避や原稿（他のプライベートリポジトリ）への取り込み状況の管理を可能するために、次のようなレビュー方法を採用した。

• フィードバックはPDFのページ単位で受ける。そのために、各ページ用のGitHub issueをあらかじめ全ページぶん用意しておく
• 指摘をするときの負荷を下げるために、PDFの各ページに、各ページ用GitHub issueへのリンクを埋め込んでおく。そこをクリックすれば、そのページに対するコメントを書き込めるページがブラウザで開くしくみ

さらに、上で紹介した経験則を踏まえて、レビュアーには下記のようなお願いをしている。

PDFを読んでページごとのissueに指摘を追記していってください。代案は不要です。なお、マンパワーの都合でissue上では無反応の可能性が高いです。ごめんなさい。

• 具体的に指摘をいただきたいポイント
  • 内容の間違い
  • 解説がほしいトピック
  • 意味が取れない段落
• 下記の指摘も歓迎です（grepをかけるので存在の指摘だけで十分です）
  • 技術用語の不統一
  • スペルミス、誤字、脱字
• 下記については、指摘は不要です（最終までには自然に直ります）
  • 日本語表記（漢字や送り仮名）の不統一
  • レイアウトの不備
  • その他、局所的な日本語の問題

前半で述べたように、そもそも適切なレビューの手法は要求事項によって変わってくるので、これがベストな技術書のレビュー手法というわけではない。 最大で十数人くらい、著者が中心になってSNSなどで直接連絡がつく範囲に依頼するなら、いまのところDropboxへのコメントはかなり手軽に思える。 ピンポイントでお願いする人がいる場合も、DropboxへのコメントやPDFへのアノテーションがベストだろう。 一方、ある程度の議論が予測されたり、原稿のバージョン管理との親和性が優先されるなら、これからもGitHubのissueを使うと思う。

そしていずれにせよ、レビュアーに何を見てもらいたいか（見る必要がないのか）、レビューにあたって最終決定権は制作サイドの独断的な判断になることについては、何らかの形でレビュアーと制作サイドとで意識共有ができているべき。