【読書】読みやすい技術書を書く技術

技術書典7で事前にチェックしており、実際に表紙と目次を見て、私の知りたい内容が書かれていると思ったので買いました。

私は技術書典7で初めて技術書を執筆して頒布したのですが、prhやRedPenなどの文書校正ツールを使いこなせませんでした。こちらの本には、それらのツールとDockerイメージ、CircleCIを使ってCIする方法が書かれているとのことなので、読んで学ぼうと思いました。

感想

「はじめに」に記載されている通り、読みやすい文章を執筆するための「環境構築」について書かれている本です。

タイトルだけ読むと、読みやすい文章の書き方について書かれている本だと勘違いしそうですが、そうではありません。

表紙はフェルメールの「天文学者」、裏表紙も同じくフェルメールの「地理学者」です。
私はフェルメールが好きで、特に左窓から光が差し込む系に惹かれているので最高です。
著作権が問題ないのかは気になるところです。

裏表紙にジョジョ第5部をパロったものが書かれているのもたまりません。
私がiOSDC Japan 2019で提出したプロポーザルと同様、執筆した時期にアニメが放映されていたのだと推測できます。

私はdocker-review+ReVIEW-Templateを使って執筆しましたが、こちらの本でも同様でした。
とてもよかったので、次回以降もこの構成とするつもりです。

プリプロセッサはよくわからなかったので、ソースコードは全て.reファイルに直接書いていました。
こちらの本を読んでなんとなく理解したので、余裕があればプリプロセッサを取り入れたいです。

prhが表記揺れを検出するツールだということを初めて知りました。
英単語の大文字・小文字違いやtypoをかんたんに検出できるので、ぜひとも導入したいです。

RedPenは試してみたのですが、指摘数が多過ぎて諦めてしまいました。
prhやRedPenの設定ファイルは「育てる」ことが大事とのことなので、諦めずに育てていきたいです。

textlintは試したことすらなかったのですが、RedPenにはないルールも多く存在するようなので、導入したいです。
RedPenと重複するルールはOFFにするのが使いやすそうです。

CircleCI上で各校正ツールを使ってCIを回す方法が、具体的に説明されていて嬉しいです。
今まではDockerイメージを使ってCIする方法がわからなかったので、こちらの本通りに組んでみたいです。
月間ビルド時間1000分までは無料なので、Re:VIEWによる執筆では無料枠に収まりそうです。

reviewdogは使ってみたいと思ったのですが、私はGitHubでプライベートリポジトリを管理していないのでおそらく使えません。
少人数で執筆するときは無料でプライベートリポジトリを使えるので、そのときはGitHubを使いたいです。

CircleCIを使ったことがないのでカスタマイズできるかわかりませんが、generateジョブは紙版、電子版、EPUB版の3つを生成するようにしたいです。
実際にRe:VIEWを使ってわかったのですが、この3つのうちどれか1つでしか発生しないビルドエラーがあったり、EPUB版のみレイアウトが崩れていたりなどがあります。
私は技術書典7の直前に初めてEPUB版を生成したのですが、どうやらレイアウトが崩れており、修正する時間がなかったため公開を断念しました。

学んだこと

  • 出ない神本より出るクソ本
    まずは書き上げ、自分が書いた文章を誰かに届けることが大事
    出なければ意味がない
  • 読者のことを考える
    読者にとって読みやすい文章かの最終判断は、校正ツールでなく自身で行う
  • 銀の弾丸はない
    どんなツールを使っても自分の実力以上には読みやすくできない
  • 伝わるかどうかは伝えてみないとわからない
    実際に読んでもらう
  • 興味のないことは伝えられない

おわりに

以下のツイートに思いを込めました。

Written by

iOSアプリを開発しています。Swift楽しい✨ Qiita:https://qiita.com/uhooi 趣味:テニス、アナログゲーム

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store