細かすぎて伝わらない『Pragmatic Terraform on AWS』を読みやすくする技術 #技術書典

今更ですが技術書典6、おつかれさまでした。ありがたいことに『Pragmatic Terraform on AWS』も物理本200部が完売しました。また、BOOTHでは10日ほどで、電子版を370名以上の方にご購入いただきました。本当にありがとうございます。

kosmos.booth.pm

本記事では、『Pragmatic Terraform on AWS』の執筆の裏側を紹介します。技術と書いてますが、ぶっちゃけタイトル詐欺です。だいたい根性でなんとかしました。

前提

執筆にはRe:VIEWを使用しました。書籍執筆が初だったのもあったので、TechBoosterさんが公開しているReVIEW-Templateをほぼそのまま使いました。先人の知恵が凝縮されており、執筆初心者でもちゃんとした本の体裁が整う素晴らしいソフトウェアです。

ReVIEW-Templateは今でこそRe:VIEW 3.1に対応していますが、筆者がRe:VIEWを導入した2019年2月初旬時点では、Re:VIEW 2.4のみの対応でした。そのため、筆者はRe:VIEW 2.4版のテンプレートを使用し、そのまま入稿まで行いました。

推敲の基本

文章の推敲については数学文章作法　推敲編 を教科書にしました。詳細は本を読んでいただきたいですが、第一章の「読者を迷わせない」を念頭に推敲を行いました。

• 似ている語句で迷わせない
• 長い文で迷わせない
• 言葉の不足で迷わせない
• 無駄な言葉で迷わせない
• 指示語で迷わせない

ReVIEW-Templateに最初から組み込まれていたprhなども活用し、表記ゆれなどの機械的に拾えるモノについては、機械的に拾うようにしました。

通しで行った推敲回数は7回です。表紙込みでB5サイズの148ページの書籍なので、相当頑張ったほうだと思います。ただ程度の差はあれ、ここまでは多くの書籍でも実施されてる内容と大差はないでしょう。この記事の本番は次からです。

インラインコード

『Pragmatic Terraform on AWS』ではかなりの頻度で、本文にコードの断片が登場します。そのコードの断片のアンダースコアが長くて見づらい、という指摘がレビューアから入りました。

たしかに間延びした印象を受けます。正直、これくらいならいいか、と放ったらかしにしていたんですが読みづらいと指摘されては直すしかありません。そこで、Re:VIEWで標準提供されている、本文中にコードを埋め込むときに使う @<code>{...} 記法を導入しました。これを使うと、等幅フォントで表示されるため見やすくなります。

問題は、本文中にコードの断片が埋まっている場所が鬼のようにあることでした。最初からやっておけば大した手間ではなかったのですが、最初に横着したせいで、150ページ近くある文章をすべて点検して修正するハメになりました。だいたい潰したと思いますが、もしかするといくつかcodeブロックになっていない箇所があるかもしれません。

しかしこれは別の問題を生み出しました。

コードの途中改行

なんと @<code>{...} 内で書いた英単語が改行される位置にあると、空気を読まずにぶった切られるという現象が起きました。@<code>{...}で囲まず普通に書いた場合は起きない現象です。文章の意味は分かりますが、圧倒的コレジャナイ感があります。

そこでどうしたかといえば、文章を書き換えました。そもそも改行される位置にあるのが悪いということで、改行される位置に @<code>{...} を書かないようにしました。文章の意味を変えずに文章の構成を変えます。

読みやすくなりましたね！お察しのとおりこの現象は @<code>{...} が含まれるすべての行で起こりえます。つまり、推敲などをして文章を変更すると、この現象が発生するリスクが常にあります。

この新たなる問題にどう対峙したかといえば、マージ前に変更行をPDFですべて目視チェックです。推敲フェーズでは毎回プルリクエストを作成して、CircleCIでPDFを自動生成して、生成されたPDFを目視チェックしてました。

文章が読みにくいから推敲してるのに、推敲したせいで変な改行が発生してまた書き直すみたいなことを何度もやりました。これは人類がやる仕事ではありません。しかし筆者にはTex力が足りなかったため、仕方なくこの苦行を受け入れました。推敲で一番ネックになったのはこの運用で、本当にしんどかったです。

ページをまたぐコード

『Pragmatic Terraform on AWS』には100以上のサンプルコードがあります。しかし、複数ページにまたがるコードは実は数えるほどしかありません。次の例は、その数少ないコードです。

実は推敲前のタイミングでは、3ページに1個ぐらいのペースでコードが複数ページにまたがっていました。そもそも1ページでどれだけの内容が入るかまったく肌感がなかったのと、単純にコードの数が多かったため、なにも考えずに書いたものをPDFにすると、結構な頻度でページをまたがってしまいました。

自分で見た瞬間に「この本、読みづらっ！」と思ってしまったため、可能な限りコードはページをまたがないようにしています。大半のコードは行数が減らせなかったため、本文の量を調整しました。あと1行減らせば全部入る！となれば、どうにかして1行削りました。あと3文字減らしたら全部入る！となれば、どうにかして3文字削りました。

数文字増やしただけで改行位置がズレてしまい、ページをまたぐコードだらけになるなど日常茶飯事でした。執筆終盤になると、奇跡的なバランスでレイアウトされているページだらけになり、推敲の難易度が爆上がりすることになりました。

ページをまたぐ注釈

Re:VIEWでは標準機能だけで注釈が書けるのですが、実際に注釈を書いてみると、長い注釈が複数ページにまたがる現象が起きました。『Pragmatic Terraform on AWS』ではさまざまなURLを注釈に書いており、その中には長いURLも少なくなかったため、結構な頻度で発生しました。

どうしたかといえば、愚直に本文の長さを修正しました。注釈に書いているURLは基本的に短くできないため、注釈もすべて一ページで収まるようにひたすら文章量を調整しました。

注釈のために、本文の意味を変えずに文章を短くするというのはなかなかの難易度で大変でした。「コードの途中改行」や「ページをまたぐコード」と同時に解決しないといけないケースでは、1行ひねり出すのに1時間かかるなんてこともありました。

ページをまたぐ文章

技術書に限らず、長い文章を書いていると、文章の途中で別ページにまたぐことがあります。この現象は非常にありふれており、大抵の書籍ではそのままです。

しかし『Pragmatic Terraform on AWS』ではこうならないよう、細かくチューニングしました。ページをまたがないようにそもそもの文章を短くするとか、ページをまたぎそうなら段落を分けるなどです。場所によっては、不自然にならない程度に手動で改ページを入れている箇所もあります。

正直やりすぎかな、と自分でも思いましたが、なんとなく後者のほうが読みやすくないでしょうか。（大差ねーだろって声が聞こえてきそうですねｗ

コードキャプション

Re:VIEWではコードブロックにキャプションをつけられるのですが、ページをまたぐ位置にコードがあると、キャプションだけ前のページに残り、コードブロックは次のページにあるという残念な状態が起きました。

対処自体は簡単で、コードブロックの直前に手動で改ページを入れることで乗り切りました。

//embed[latex]{
\clearpage
//}

このような記述を入れると、次のようになります。

このソリューションの問題は、改ページを入れる手前の文章量が変わって、改ページすべきでない状態になっても問答無用で改ページが入ることです。ある問題の解決策が、別の問題を生むという典型例ですね。

どうしたかって？もちろん、全ページ目視チェックです。

コード内の改行

『Pragmatic Terraform on AWS』では、コードブロックに行番号を入れることにしました。本文内で「○○行目のように△△する」みたいな記述を書きたかったからです。行番号の追加自体は、Re:VIEW標準で listnum 記法というのが用意されていたので、それを使うだけでした。困ったのは一行が長いコードです。たとえば、書籍内で登場するコードに次のようなものがあります。

resource "aws_route53_record" "example_certificate" {
  name    = aws_acm_certificate.example.domain_validation_options[0].resource_record_name
  type    = aws_acm_certificate.example.domain_validation_options[0].resource_record_type
  records = [aws_acm_certificate.example.domain_validation_options[0].resource_record_value]
  zone_id = data.aws_route53_zone.example.id
  ttl     = 60
}

これをそのままPDF化するとこんな感じです。

考えるまでもなくダメダメです。そこで最初は、なにも考えずに改行を入れました。

今度は同じ行として扱ってほしいのに、違う行と認識されています。まぁなんとなくは分かるし、読者も察してくれる気もしますが、できればなんとかしたいところです。そこで最終的にはサンプルコードに次のような、魔法の記述を加えました。

@<embed>{|latex|\allowbreak}　 @<embed>{|latex|\(\hookrightarrow\)}

するとPDFはこんな感じになります。

コードの途中で改行しつつも、なんとなく同一行であるかのように感じられないでしょうか。これは原稿上では次のようになっています。

resource "aws_route53_record" "example_certificate" {
  name    = aws_acm_certificate.example.domain_validation_options[0] @<embed>{|latex|\allowbreak}　 @<embed>{|latex|\(\hookrightarrow\)} .resource_record_name
  type    = aws_acm_certificate.example.domain_validation_options[0] @<embed>{|latex|\allowbreak}　 @<embed>{|latex|\(\hookrightarrow\)} .resource_record_type
  records = [aws_acm_certificate.example.domain_validation_options[0] @<embed>{|latex|\allowbreak}　 @<embed>{|latex|\(\hookrightarrow\)} .resource_record_value]
  zone_id = data.aws_route53_zone.example.id
  ttl     = 60
}

ちなみに、大半のコードは @mapfile 記法というものを使って、外部ファイルを直接読み込んでいます。@mapfile を使えば、コードの変更がダイレクトに原稿に反映されて楽だからです。しかし、この対応をした場合、コードが原稿にべた書きされることになり、コードを変更すると原稿も変更しなければなりませんでした。もちろん、すべて手動で変更を反映しました。

それほど数が多くなかったことが、救いといえば救いでした。

コラムで埋める

『Pragmatic Terraform on AWS』のいくつかの章では、コラムがあります。実はそのコラムの大半は、入稿二週間前まで存在しませんでした。

前述のとおり、かなり細かいチューニングを行ってきましたが、その結果、章の最後のページの大半が空白になるという状況が発生しました。もちろん、かなり推敲したあとのことなので別にこのままでも問題ないわけですが、ボツネタが大量にあったのでいくつか組み込みました。

たとえば、ALBを扱う章の本文では本番運用を想定し、削除保護を有効にするよう説明しています。しかし、サンプルコードをそのまま写経すると、ためしに作ったリソースを削除しようとしたときにエラーになってしまいます。知っていればなんてことはないのですが、はじめてTerraformに触る人もいると考えられたため、先回りして削除方法を解説しました。

このように、本筋の流れで書くとちょっとテンポが悪くなるけど、知っておいたほうがいい情報を追加していきました。技術書典の本は、書き手が「好き」を早口で詰め込んでいると評されていますが、まさにそれを地で行っています。

自分で言うのもなんですが、『Pragmatic Terraform on AWS』は恐ろしく情報密度が高い構成になっています。読みやすさを考慮すると、本当はもう少し遊びがあるほうがいいんですが、情報密度については筆者のエゴを優先し、詰め込めるだけ詰め込むことにしました。

神は細部に宿る

本を書いてみて実感したのは、世の中に出ている本の圧倒的読みやすさです。Re:VIEWで本文を書いてPDFに変換したときの雑然とした状態に驚きました。図が大きすぎて謎の巨大な空白があったり、サンプルコードがページをまたぎまくり、とても読みづらい状態でした。先人たちが作ってくれたテンプレートを使うだけでは、まだ足りないということを痛感しました。

もちろん本は内容が第一で、中身のない本をいくら読みやすくしても仕方がありません。しかし、本の内容がいかに素晴らしくとも、体裁が整っていないせいで頭に入ってこないのであれば意味がありません。いかに素晴らしい設計でも、インデントがグチャグチャのコードが読めないのと一緒です。

本の体裁を整える作業というのは、それ自体が価値を生むことはありませんが、可読性・変更容易性には大きな影響を与えます。もう少し筆者にRe:VIEWやTexの知見があれば、自動的に対応できる箇所もかなりあるはずですが、今回は根性で乗り切りました。頑張ってチューニングしていたので「商業誌クオリティ」と評されたのは嬉しかったです。どうみても「プロの仕事」とは言えないプロセスですがｗ

この記事で書ききれなかった小さな工夫は他にもたくさんありますが、それこそ「細かすぎて伝わらない」のでこのあたりにしておきます。ぜひ本を読むときは、中身だけでなく読みやすくするための工夫にも目を向けてみてください。たくさんの小さな工夫が散りばめられているはずです。

引き続きBOOTHで『Pragmatic Terraform on AWS』を販売しているので、未読の方は読みやすくする工夫にも着目しながら読んでいただけると嬉しいです。

kosmos.booth.pm