2018/10/25

書籍『ゼロから創る暗号通貨』をどう読むか

濵津誠 著『ゼロから創る暗号通貨』(2018年10月、PEAKS発行)の編集をお手伝いしました。この本はどんな本かというと……

  • 土台となるP2Pネットワークから暗号通貨を自前で作ってみることで、ブロックチェーンを応用したまったく新しいサービスと未来を創るところまで意識できる本
  • 著者の濵津さん自身が教師役となり、ブロックチェーンの「うさんくさくない」部分の全体がわかるように、読者をひっぱっていってくれる本

要するに、ブロックチェーンの技術を通して、濵津さんという凄腕技術者が読者のメンターになってくれる本です。これまでクラウドファンディングで出資者しか読めなかったのが、今日から一般にも購入できるようになりました!

ゼロから創る暗号通貨

ゼロから創る暗号通貨

以下は、個人的な回想と、本書でぼくが何をしたかの舞台裏。

暗号通貨についてざっくりと知りたいなと思って、「暗号通貨」で検索してみると、投資して儲けたい人向けの記事と、通貨としての側面について考察する社会派な記事ばかりがトップに並びます。この結果だけ見ると、だいぶうさんくさい。でも、暗号通貨というかブロックチェーンって技術的には面白そうなトピックだし、キャッチアップはしておきたいな。

というわけで、その昔、サトシ・ナカモトの原論文(PDF)とされているものを斜めに眺めてみたことがあります。以下、たぶんそのころにぼくが感じたであろうこと。

どうやら、ビットコインにおける「コイン」とは、取引の記録をつなげたものらしい。 ということは、そのコインが使われた取引の記録を、そのままコインとして使おうという発想か。 で、この論文の冒頭にあるのが、取引の連鎖としてのコインの構成図というわけね。 ブロック暗号化方式におけるブロックチェーンみたいだな、ああ、それで「ブロックチェーン」っていうのか。 しかし、原論文でその図が出てくるところには、「We define an electronic coin a chain of digital signatures」(電子コインとは、ディジタル署名の連鎖のことである)と書いてあるぞ。 このディジタル署名で、コインを使った人を特定しようというのだろうか。 分散されたタイムスタンプサーバで「Proof of Work」を計算し、その「証拠」をブロックに埋めることで、CPUパワーに基いた安全な取引が実現する? 何をいってるのかさっぱりわからないぞ。 ブロックの図の中に出てくる「nonce」が「証拠」のことなのかな……。

論文だからしょうがないかもなんだけど、だいたいこんな感じで、半分くらい読んだところで放置してました。こんな「ふわふわ」した概念を具体的にどうやって「通貨」として使えるように実装できるのか、そもそも、この論文のどのへんが画期的なのか、まったく想像つかないぞ!

PEAKSの永野さんから「暗号通貨の本をクラウドファンディングで出すことになったので編集を手伝ってほしい」という相談を受けたのは、そんなときのことでした(うそです、実際に論文を読んでみたのは4-5年前のこと)

PEAKSについては、『プロフェッショナルIPv6』と同時期にクラウドファンディングの技術書を始めたシンクロ改行ニシティというくらいの情報しか持っておらず、ただiOSとかAndroidとかの現場よりの内容が多い印象だったので、暗号通貨というテーマはかなり意外に感じたのを覚えています。それなのにぼくに編集依頼がくるということは、もしかしたらだいぶ固い感じの内容なのかなあと勝手に想像していました。

ところが、著者の濵津さんの原稿をはじめて目にして、肩透かしを受けることになります。原稿に対する第一印象は、「ラノベだこれ」

しかも、その時点で出来上がっている原稿の大半は、ぜんぜん暗号通貨っぽくない。ひたすらPythonでP2Pネットワークを作り始めているのです。確かに暗号通貨って分散ネットワーク上のアプリケーションだし、書名のとおり「ゼロから創る」んだろうけど、本の構成として正直これでいいのだろうか。わざわざ「創る」という表記になってるのも気になる。それに、対話形式の本文って、これまたかなり難易度が高い手法を選んだな……。

そんなことを思いつつ、まずは文章になっている情報を整理するつもりで読み始めて、1章と2章を読み終えたところで、この本が対話形式なのは単なる思いつきではなく完全に意図的だなと気づきました。これなら、「マンガでわかる」みたいな本と同じように、頭ごなしに概念から入るのがつらい人向けに最初の一歩から教師役が寄り添って説明していく本にできそう。そして暗号通貨というのは、数年前にぼく自身がぶちあたったように、

  • なぜそういう概念を導入したいのか
  • その概念はどういう技術に落とし込めるのか
  • それらを組み合わせて何ができるのか
が見えにくいテーマなのかもしれず、それならば対話形式はもってこいかもしれない。

とはいえ、対話形式って、ケレン味を感じさせることなく読ませるのが難しいんですよね。そもそも登場人物の役割分担を書き分けるのが難しい。生徒役がありえないほど高スキルな質問をしてしまう、みたいなことがないようにしないといけない。かといって、先生役がひたすら説明するのもうまくない。ぼくが最初に原稿を見たのは、ちょうどサポーター向けの最初のプレビューが始まっていたころだったのですが、そのへんの調整はまだまだ必要そうな状態に見えました。

そこで、まずは教師役の兄と生徒役の弟の口調を整理しつつ、弟のペルソナを「Pythonでコードはごりごり書けるけど技術の背景にある設計思想はまだ読み取れない学生」としつつ、それがぶれないように兄と弟のセリフを整理しました。兄の説明についても、飛躍を埋めるような調整を全体に入れました。ついでに、なぜ暗号通貨の本を読んでいるはずなのにP2Pネットワークを創らされているのか動機を明確にしたり、いま全体のうちどの部分を説明しているのか迷子にならないようにサブ見出しを適宜入れたり、そういう通常の編集も加えていきました。

ちょっと驚いたのは、ぼくの本文編集と並行して、hagino3000さんが全体にわたってPythonのコードをレビューされていたことです。これでは弟が凄腕のPythonistaになってしまうー、という危惧を感じないではなかったのですが、これは読者にとってはすごくうれしいことだと思いました。なるほどPEAKSではそういうところにちゃんとコストをかけているのか、という驚きでした。

最終的に完成した『ゼロから創る暗号通貨』という本、すでにクラウドファンディングで支援された方々の手元には届いているのですが、今日からPEAKSのサイトで一般発売も開始したようです。

ゼロから創る暗号通貨

ゼロから創る暗号通貨

実際に読むとわかりますが、この本では暗号通貨をやるのにP2Pネットワークから本気で作り始めます。それは、P2Pネットワークにおいて個々のノードがブロックチェーンを構成するという点が、リアルな通貨との交換可能性みたいな部分にとどまらず、暗号通貨の技術的な応用可能性が開けてくるところだからです。「土台となるP2Pネットワークから暗号通貨を自前で作ってみることで、ブロックチェーンを応用したまったく新しいサービスと未来を創る」ところまで意識できる内容になっているのが本書の魅力だと思います(それで書名は「作る」じゃなくて「創る」だったんだね)。もちろん、「著者の濵津さん自身が教師役となり、ブロックチェーンの「うさんくさくない」部分の全体がわかるように、読者をひっぱっていってくれる本」という点も魅力です。上記のリンク経由で本を買っていただけると私にキックバックがあるそうなので、暗号通貨のその先にあるブロックチェーンの応用が気になる方、濵津さんみたいな技術者になりたい方は、ぜひ!

っていうか、このブログ記事を書くのに、さっきサトシ・ナカモトの論文を読み返してみたんですよ。そしたら、たぶん『ゼロから創る暗号通貨』をひととおり読んだおかげで、するするわかる。ような気がする。

2018/08/15

日本語の編集をしていてよく直すパターン15選(増えるかも)

校正のバイトをしててよく直す箇所10選|bxjp|note(ノート)』という記事を読んで、よくパターン化されていて素晴らしいって思っていました。ところが、記事の趣旨を勘違いした方からの冷たい反応を受けて有料にされたということで、あまりも残念なので自分の立場で再編してみました。1~10は元記事のパターンに対してぼくの考え方を添えたもの、A以降は、元記事を見てぼくが反射的に思いついたパターンです。

まあ、こういうパターンは便利だけど、パターン化できる修正を積み重ねれば悪文がなくなるほど自然言語は簡単ではないので、編集や校正をする人はたいへんですね。 自分は、こういうパターンも直すけれど、段落の役割を整理する、みたいな修正のほうが専門です。(専門とは?)

追記:これは文の書き方指南じゃなくて、文の編集校正で何をやってるか報告です。


1. 順接の「が」が頻出

順接の「が」は撲滅を目指すべきです。なるべく減らす、とか言ってる場合ではない。

2. 「も」を使いがち

「も」が必要以上に使われているのは論外として、「も」の位置も直したほうがいい場合っていうのが意外と多い。つまり、「も」の位置を直したほうがいい場合っていうのも意外と多い。

3. 「することができる」を使いがち

発話で「〇〇できる」と短く言い切るのは不安かもしれませんが、書き言葉では「することが」成分はおおむね不要です。ざくざく削ぎ落としていきます。

4. 途中で主語が入れ替わっている

書き手が長い文を書いていると、しばしば主語が入れ替わってしまう。ところで、前の文では主語が入れ替わっていて、日本語では許容される場面も多く、徹底するのは難しい気がします。とはいえ、やっぱり読みやすくはないので、たいていの場合は文章ごと書き直します。

5. 意味のまとまりで「、」を打たない

読点は意味の区切りとは限らないので難しいなあ(そもそも意味とは)。ただ、発話の調子に合わせて入れるものではない、とだけは言えます。

6. 列挙するときに余計な語句を入れてくる

これはよくわからなかった。

7. そこ漢字?ってところが漢字

~と言う、無い、出来る、何れも漢字にして欲しく無い。

8. 同じ表現・言葉が近い位置に出てくる

同じものは同じ表現にするのが原則。そのうえで、微妙に違う話が同じ表現になるのを避けたい場合、箇条書きにするといった工夫を施す場合があります。

9. 表現がバラエティ豊かすぎる

非標準的な語法やレトリックは、多用すると印象が悪いので、きもち控えめに修正することがよくあります。

10. 同じことを書いている&省略せずに書いている

どんなに重要な話でも、同じ内容の文が近距離で繰り返されている場合には、ざっくり要約するか、別の表現に書き換えるなどします。

A. 因果関係を示すために「ため」を使わない

「ため」は多義的なので、目的を示すための利用に限定していきます。

B. 「の」でなくてもいい場所から「の」を追放する

「ぼくのかんがえたさいきょうのまとめ」よりも「ぼくがかんがえたさいきょうのまとめ」

C. 「イ形容詞+です」を避ける

わりと多いです。うまくないです。

D. 「行う」を減らす

便利なのでつい多用しがちだけど、だいたいは動詞ひとつで言い換えられます。「することができる」と似てるかもしれない。

E. 目的語の不足や、位置の修正

「「何を」がないことが多い。」みたいな文だと、わかってる人にしか伝わりません。「読者が、文脈から動詞の対象となるモノを推察するしかない文章が少なくありません。」くらいたっぷり書いてほしいわけです。それをさらに編集で「動詞の対象となるモノを、読者が文脈から推察するしかない文章が少なくありません。」と直したりします。

2018/07/07

技術書をクラウドファンディングで出版してみた

あきみちさんから、「IPv6本を出すということで、クラウドファンディングで協賛を呼びかけよう」(原文ママ)というアイデアを聞いたのは、TwitterのDMのやり取りを読み返すと2016年11月23日のことだったらしい。 DMには時刻が表示されないので正確な時間はわからないけど、その後のやり取りがいつの間にか11月24日になっているので、たぶんそういう時間帯だ。

それに対するぼくの最初の返答は、「それは既存の出版社だと面倒そうだ」(原文ママ)だ。 言外に「うち(ラムダノート)ならできるよ」が含意されていることは、起業前からいろいろ相談にのってくれていたあきみちさんには間違いなく伝わる。 とはいえ、そのころはまだ『プロフェッショナルSSL/TLS』も制作中だったし、直販ストアもなかったし、ラムダノートは胸を張って「出版社」と言える状態ではなかった。

そもそも、あきみちさんやぼくは技術自体というより技術解説でご飯を食べている人間であり、必要としている人がいる内容だからといって、採算度外視では動けない。 当時はまだクラウドファンディングで技術書を作るという先行事例もなく、どれくらい集めればいいのか、どれくらい集まればいいのか、どういうふうに具体化すればいいのか、まったく見当もつかなかった。 にもかかわらずぼくは、あきみちさんにいくつか質問したあとで、「だれにでも通用するやり方じゃないですが、あきみちさんでIPv6の本なら確度高い。」(原文ママ)と応じていた。 はっきりいって軽率である。 まあでも、考えていてもわからないことは、やってみるしかないので、当時のぼくはやってみることにしたのだろう。

それから急いで企画書っぽいものを作り、直接支援をお願いできそうな会社にあきみちさんから打診し、ぼくのほうでもMakuakeに問い合わせを入れた完成品をCC BY-NC-SAで公開することをふくめて、翌月にはだいたいプロジェクトの形が決まった。 当時の企画書の1枚めはこんな感じ。

このときの企画書をいま見返すと、本の構成も、収益化のモデルも、基本的なコンセプトはこの時点からほとんどずれていない。 本の構成については実際に本を読んでもらうとして、ここでは収益化のモデルという視点で現時点で個人的に感じていることをメモしておこうと思う。

「こういう本が最小限の負担で読める世界」に出資してもらう

『プロフェッショナルIPv6』の商売モデルは、たぶんこんな感じになっている。

つまり、この本の著者と出版社には、本という商品だけでなく、「こういう本が最小限の負担で読める世界」を実現することへの対価として出資してもらえたし、応援してもらえた(本当にありがとうございます)。 そうした出資を広く集めるうえでクラウドファンディングという方法は相性がよかったし、任意の金額を著者に直接渡せるという電子版の提供方法を手軽に導入できたのは大きかった(BOOTH、まじ便利)。

一方、多くの本の企画は、基本的にはこんな商売モデルでやっている。

この方法だと、動物の絵がカバーにあるわけでも全国の書店にフリー入帳で配本できるわけでもない新興の出版社から発行される「IPv6の解説書」は、完全に「知る人ぞ知る」ものになっていただろう。 あきみちさんとぼくの実情からすると、最悪、陽の目をみなかった可能性もある。 こうやって多くの人に届けることはできなかったかもしれないし、著者に利益を還元できなかったかもしれないし、うちも資金繰りに困っていたかもしれない。

教訓と抱負

『プロフェッショナルIPv6』は、たぶん、「こういう本が最小限の負担で読める世界が欲しい」という人を巻き込めた。つまり、「読ませたい人」の支援で成立した。 そして、この事実からは、技術書の出版に従事している自分たちにとっての教訓めいたものが導き出せる気がしている。

実のところ、技術書の多くは、これまでだって「読ませたい人」からリソースを分けてもらうことで「商売」をしている。 その最たる相手は、印税収入を期待せずに採算度外視で執筆してくれる著者。 それから、謝辞と献本程度の対価で内容のレビューをしてくれる有識者や、やはり献本程度の対価で宣伝をしてくれるインフルエンサー。 みんな、「読ませたい人」として、自分が持っているリソースを本という商品に投下してくれている。 出版社は、そうした人たちの善意に頼ることで、対価を払ってまで読みたいことを自覚している人の総数だけでは成立しないかもしれない本を作って売るという商売をかろうじて維持している。

ぼくら版元の編集者の人間は、そのことに意識的でなければならないと思う。 版元の編集者も「読ませたい人」ではあるだろうけど、その実現のために持ち出しで出資をしているわけではないので(むしろ多くの場合は十分な対価を得ている)、気を抜くとこの事実を忘れがちになるので本当に注意しなければならない。 ページあたり数百円とかで編集制作をやってくれる編集プロダクションが版元編集者のコストを肩代わりしている可能性にも意識的であるべき。閑話休題。

教訓は、なにも警鐘を鳴らす方向だけではない。 『プロフェッショナルIPv6』では、「こういう本が最小限の負担で読める世界が欲しい」という人から直接出資をしてもらったことで、商売として出版できるチャンスが広がった。 あきみちさんという著者が十数年かけてインターネット上で築き上げた人徳があってはじめて実現するクラウドファンディングではあったけれど、とにもかくにもこういう形で出版ができたということは、「読みたいことを自覚していてお金を出してくれる人」の絶対数が多くないことが多い技術書みたいなジャンルの出版にとっては、わりと未来がある話なんじゃないだろうか、とも思う。

そんなわけで、『プロフェッショナルIPv6』をひとまず公開にまでこぎつけた現時点で個人的に感慨深いのは、クラウドファンディングという手段の面よりも、「こういう本が最小限の負担で読める世界」に出資したいと感じる人にうまく届けられたかな、という点にあったりする。 締め切りに追われるのが精神的につらいのもあって、正直なところ、これからクラウドファンディングで本をばんばん企画していく予定はない。 でも、「こういう本が最小限の負担で読める世界が欲しい」、もうちょっと厳密に言うと、「こういう技術情報がある世界が欲しい」という人や組織に出資してもらえるような企画、あるいは仕掛けを考えて、そのうえでコンテンツの制作をこれからもがんばっていければ嬉しいなという気持ちでいる。

宣伝

というわけで、ラムダノートの本をよろしくお願いします。

https://www.lambdanote.com/

プロフェッショナルIPv6

2018/04/30

コマンド定義の中で\catcodeを変える

LaTeXではシングルクォート記号がデフォルトで「」になる。Unicodeでいえば、RIGHT SINGLE QUOTATION MARK(U+2019)。この挙動は、本文ならよいのだけど、等幅フォントにするような場面では都合が悪い。等幅フォントのときにみんなが期待するシングルクォートは「'」である。

みんなが期待する挙動なので、当然、そのためのパッケージがすでにある。upquoteパッケージである。しかし、このupquoteパッケージは、\verbコマンドおよびverbatim環境向けに作られている。fancyverb環境やalltt環境でも使えるが、\textttコマンド内の挙動には影響しない。つまり、upquoteパッケージを使っても、\texttt内のシングルクォート記号は「」になる。

\texttt{...}の中でシングルクォート記号を直立タイプ「'」にするにはどうするか。すぐに思いつくのは、「'」をアクティブ文字にして、OT1/cmttの\char13にするという方法。あるいは、textcompパッケージで提供されている\textquotesingleにするという方法。実際、upquoteパッケージの実装もそのようになっている。その方針をそのまま実装するとこうなる。

\let\orgtexttt\texttt
\def\texttt#1{%
  \catcode`'=\active
  \def'{\textquotesingle}
  \orgtexttt{#1}}

もちろん、これは動かない。この\defの中身はすでにTeXの入力ルーチンで読み込まれているので、\def'{\textquotesingle}の時点では「'」がアクティブ文字になっていない。そのため、ふつうの文字である「'」に対して\defすることになってしまうからだ。結果として、「コントロールシーケンスやアクティブ文字であるべき場所にふつうの文字がある」というエラーになる。

! Missing control sequence inserted.

                \inaccessible

こういう場合の常套手段として、「\lowercaseトリック」と呼ばれるものが知られている。このトリックのポイントは、\lowercaseというコマンドの引数が、「すべての文字を小文字として解釈してくれて、しかもカテゴリーコードに関しては無視してくれるような世界」になることにある。そういう世界で、「'」のことを、なにか「\defの1つめの引数に置いても怒られない都合がいいアクティブ文字」の小文字にしておく。幸い、TeXには、そのような都合がいい文字がある。「~」だ。\def~{...}であれば、\def\texttt#1{...}の定義部の中にいきなり書いても怒られない。そこで、「~'の小文字」ということにしておいて、\def~{...}と書けば、この\defにより実際には「'」に対する定義が書けることになる。

あるアルファベットに対する「小文字」を定義するためのプリミティブは\lccodeだ。これを使い、「'」のことを「~の小文字である」ということにして、その文脈で\lowercase{...}内で\def~{\textquotesingle}すればよい。

\def\texttt#1{%
  \catcode`'=\active
  \begingroup
    \lccode`~=`' %
    \lowercase{\endgroup
      \def~}{\textquotesingle}
  \orgtexttt{#1}}

\lccode`~=`'のスコープを定めている\begingroup\endgroupの組に対し、\lowercase{...}のカッコがきちんと入れ子になっていない。あまつさえ\def~{\textquotesingle}にも「}」がまたがってしまっている。気持ち悪いかもしれないけど、これで問題はない。少なくとも、\def~\begingroup\endgroupの中に入れてしまうと、この\defがローカルになってしまうので、「'」がアクティブになるだけなって定義がないままとなりエラーになってしまう。

! Use of ' doesn't match its definition.

まあ、\gdefにすればいいだけだけど。

\def\texttt#1{%
  \catcode`'=\active
  \begingroup
    \lccode`~=`' %
    \lowercase{%
      \gdef~}{\textquotesingle}\endgroup
  \orgtexttt{#1}}

(ところで、\endgroup\lowercase{の直後で問題ないことの根拠は、正直なところよく理解していない。\lowercaseが大文字小文字の対応表をメモリに展開するのが引数を読む前、だからなんだろうなあ。)

さて、\lowercaseトリックのおかげで「'」がアクティブ化される前に「\def'」と書くことを回避できたので、こでれエラーにならずに動く。しかし、挙動は依然としておかしい。ブロック要素で最初に登場する\textttの中では「'」の定義が効いておらず、その後ろに出てくる「'」が、\textttの中だろうが外だろうが\textquotesingleになってしまうのである。

*\texttt{\show'}
> the character '. % \textttの中だけど、文字
...
*\show'
> '=macro:
->\textquotesingle . % \textttの外だけど、アクティブになってる
...
*\texttt{\show'}
> '=macro:
->\textquotesingle . % 2つめの\textttの中ではアクティブに
...

最初に登場する\textttの中で「'」の定義が効かない原因は、すぐにわかった。\textttの引数はすでに読み込まれているから、「'」に対する\catcodeは効いてないのである。\defに対しては\lowercaseトリックのおかげでごまかせたが、この状態では\textttの引数に対して「'」が\textquotesingleとして扱われることはない。

この欠陥に対処するには、\textttの引数が読み込まれるのを遅らせればいい。そういう場合の常套手段は、マクロの展開を二段階にしてサブのほうで引数を読み込ませる、というもの。つまりこんなふうにする。

\let\orgtexttt\texttt
\def\texttt{%
  \begingroup
    \catcode`'=\active
    \x@texttt}
\def\x@texttt#1{%
  \begingroup
    \lccode`~=`' %
    \lowercase{\endgroup
      \def~}{\textquotesingle}
  \orgtexttt{#1}
  \endgroup}

これで、目的のマクロそのものは完成した。

これにて本件は落着といたす、でもいいんだけど、1つ前の定義が「最初に登場する\textttより後ろで、\textttの中だろうが外だろうがシングルクォートが\textquotesingleになってしまう」という挙動だったのが謎い。まったく\textquotesingleにならない、というなら納得できるんだけど、なぜ\textttの引数内で閉じているはずの\catcode`'=\activeが外に漏れてしまっているのか。

どう考えても、オリジナルの\textttの定義に何かある。 しょうがないのでlatex.ltxを覗くと、\textttの定義は事実上こうなっていた。

\DeclareRobustCommand\texttt[1]{%
    \ifmmode
      \nfss@text{\ttfamily #1}%
    \else
      \hmode@bgroup
       \text@command{#1}%
       \ttfamily\check@icl #1\check@icr
       \expandafter
      \egroup
    \fi}

なんなんだよ、この下から3行めの\expandafter。。これのおかげで、\texttt(を再定義したものの中にある\orgtexttt)の引数が読まれるとき、もりもり後ろのほうまで読まれてしまって、\catcode`'=\activeがしばらく先まで有効になってしまっていたっぽい。

この\expandafterは、\textttに限らず、NFSSが提供するフォント変更コマンドすべてに登場する(ようなマクロになっている)。これ、なんのために必要なの?

なにも謎くなかった。先の動作しない\textttの定義で\catcode`'=\activeは閉じてない。ZRさんありがとうございます。

2018/03/05

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

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

一方、基本的に無償で、完成した書籍の献本と謝辞への掲載くらいを前提に、あくまでもベストエフォートで発行前の本の内容を見てくださいというお願いを第三者にすることもある。 この場合の第三者というのは、制作中の書籍の想定読者だったり、出版後の書籍を対象読者へ紹介してくれそうな立場の人だったりする。 このようなプロセスを制作に取り入れる習慣は、とくにここ数年の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を使うと思う。

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

2018/01/12

RubyでつくるRuby発売中

カート埋め込みのテスト。デフォルトだと書籍ページへのリンクにはならないのかな。カートに入れてしまったときに画面に常駐するカートボタンは、数をゼロにすると消えるようです。