出ない神本より出るクソ本 〜『読みやすい技術書を書く技術』の第1章と頒布情報〜 #技術書典

読みやすい技術書を書く技術』は、読みやすい文章を書くための「校正環境」を構築する本です。この本では、CircleCIを使って継続的に文章を校正する仕組みを整えます。技術書のような長い文章を書く人には、特に有益です。技術書典7で頒布予定なので、ぜひチェックいただければ幸いです。

techbookfest.org

CIで校正チェックすることに興味はあるけど、そこまで手が回らないんだよな〜と思っている人いませんか。この本はあなたのために書きました。この本を読めば誰でも、CircleCIで最高の校正環境が構築できます。

この本を読むことで学べること

読みやすい技術書を書く技術』では、次のようなことを習得できます。

特に技術書典で本を出すような人には、役立つ技術ばかりです。すべて動作するサンプルコードがつくため、写経するだけでもすぐに役立ちます。 さて本記事では、「読みやすい技術書を書く技術」の第1章をまるまる公開します。第1章はツールの話ではなく考え方を説明しています。それではどうぞ!


 

第1章 出ない神本より出るクソ本

この少し刺激的な章タイトルは、同人誌制作の格言として知られています。 テクニカルな話へ入る前に本章ではまず、読みやすい文章を書くための心構えを学びます。

1.1 完璧を目指すよりまず終わらせろ

本書を手に取ったあなたは、読みやすい文章を書くことに関心があるはずです。 仕事でドキュメントを書くことは頻繁にあります。 技術ブログを書いている人もいるでしょう。 もしかすると技術書を書いているのかもしれません。

いずれにせよ文章を「書く」というプロセスにおいて、もっとも難しいことは終わらせることです。 少しでも読みやすい文章にしたいという気持ちは、多くの人が抱く感情です。 しかし完璧主義を貫いた結果、アウトプットできなければ意味がありません。

本書の題材となっている校正環境の構築は「沼」です。 いくらでも時間を使うことができます。 しかし、もっとも大切なことは書き上げることです。 どれだけ完成度が低くてもまずは書き上げ、あなたの文章を誰かに届けましょう。

1.2 読者のことを考える

数学文章作法 推敲編』という推敲をテーマにした本があります。 この本では「読者のことを考える」という哲学を根底に、読みやすい文章へ書き直す方法を説明しています。

この「読者のことを考える」という哲学は極めて重要です。 小手先のテクニックよりもまず、読者のことを考えているかどうかで読みやすさは大きく変わります。

本書では複数の校正ツールを導入します。 校正ツールは有益なアドバイスをたくさん提供してくれます。 しかし、過信してはいけません。 文章を修正するかどうかは、読者のことを考えたうえで「あなた」が最終的に判断するのです。

1.3 校正ツール

文章を書く人は、自分の文章を完全に理解できます。 しかし他の人にも伝わるかどうかは、読んでもらうまで分かりません。 それを判断するためには、誰かにレビューをしてもらう必要があります。 ところがこのレビューというのは、それほど簡単ではありません。

まずレビューアを探し出す必要があります。 また探し出せたとしても、複数回レビューを引き受けてもらうことは難しいです。 通常は1回、多くても2回程度になるでしょう。 複数回レビューを受けたいなら、複数人のレビューアを確保する必要があります。

つまり「書く」というプロセスは、フィードバックサイクルを回すのが意外と難しいのです。 そこで頻繁にフィードバックサイクルを回すため、校正ツールを導入します。

校正ツールは、機械的に読みづらい文章を検知して教えてくれます。 本当に一切空気を読まず、物申してきます。 最初は少しばかり口うるさいですが、いったん我慢しましょう。 謙虚にアドバイスを受け入れると、読みやすさがグッと向上します。

1.4 継続的ライティング

校正ツールは継続的インテグレーション(CI)とのコンボが強力です。 ソフトウェア開発者であれば、CIでテストを回してコードの健全性をチェックしているでしょう。 それと同じことをするのです。 本書では次のような校正環境を構築します。 原稿を変更したらプルリクエストを出して、CircleCIで校正ツールを動かしてチェックします。 問題があればエラーで落としてGitHubへコメントし、グリーンになるまで修正を続けます。

f:id:tmknom:20190916234825j:plain

ソフトウェア開発で当たり前に行っていることを、「書く」というプロセスにも取り入れましょう。 まるでチームメンバによるコードレビューを受けるように、校正チェックを受けるのです。 常に校正チェックをしていれば、技術書のような長文でも読みやすさを維持できます。 頻繁なフィードバックサイクルは、読みやすさの向上に大きく貢献します。


 

頒布情報

ブログで公開するのはここまでです。興味を持たれた方はぜひ、技術書典7へ遊びに来てください。 ここからは大きく話を転換して、技術書典7での頒布情報をお届けします。

読みやすい技術書を書く技術は『【お20C】KOS-MOS』にて頒布します。「お20C」は3Fになります。

techbookfest.org

また頒布価格は「1,000円」で、頒布形式は次のとおりです。

  • 物理本+電子版特典付き
  • 電子版(ダウンロードカード単品)

どちらも1,000円です。値段差はありません。

電子版はpdfとepub形式のファイルをパスワード付きのzipでまとめて、BOOTHでダウンロードできるようにします。ダウンロードURLとパスワードはダウンロードカードに記載して頒布します。

物理本は400部持っていきます。現在の被チェック数からすると、売り切れの可能性もあるため、物理本が欲しい場合はお早めにお越しください。ダウンロードカードは800枚持っていくので、いつ来ても大丈夫だと思われます。たぶん。

ダウンロード販売

技術書典後になりますが、BOOTHにて電子版のダウンロード販売に対応します。技術書典に都合がつかない方や、遠方で来ることができない方はダウンロード版をご利用ください。ダウンロード版のページを公開したらあらためて告知しますが、そのうち下記リンクにダウンロード版のページが追加される予定です。

kosmos.booth.pm

目次

目次は次のとおりです。 『読みやすい技術書を書く技術』ではすべてDockerベースで操作するので最初にDockerの基礎を学びます。次に技術同人誌の執筆でおなじみのRe:VIEWに触れます。

校正ツールは4〜6章で、prh・RedPen・textlintの使い方を習得します。7〜9章で校正ツールをCircleCIに組み込み、GitHubに通知できるようにします。またPDFも自動生成し、生成したPDFへGitHubから直接アクセスできるようにします。締めくくりの10章では、ツールの限界とその先へ進むためのヒントを提示します。

 1章 出ない神本より出るクソ本
   1.1 完璧を目指すよりまず終わらせろ
   1.2 読者のことを考える
   1.3 校正ツール
   1.4 継続的ライティング
 2章 Docker
   2.1 Dockerとは
   2.2 Dockerのセットアップ
   2.3 Dockerの使い方
 3章 Re:VIEW
   3.1 書籍執筆ツール
   3.2 Re:VIEWとは
   3.3 Re:VIEWのセットアップ
   3.4 Re:VIEWの使い方
 4章 prh
   4.1 prhとは
   4.2 prhのDockerfile
   4.3 prhの使い方
   4.4 prhの設定
   4.5 prhのエラーを抑制する
 5章 RedPen
   5.1 RedPenとは
   5.2 RedPenのDockerfile
   5.3 RedPenの使い方
   5.4 RedPenの設定
   5.5 RedPenの主要な設定項目
   5.6 RedPenの無効化すべき設定
   5.7 RedPenのエラーを抑制する
 6章 textlint
   6.1 textlintとは
   6.2 textlintのDockerfile
   6.3 textlintの使い方
   6.4 textlintの設定
   6.5 textlintの主要な設定項目
   6.6 RedPenと重複する設定項目
   6.7 textlintのエラーを抑制する
 7章 CircleCI
   7.1 CircleCIとは
   7.2 CircleCIのセットアップ
   7.3 CircleCIの設定
   7.4 校正ツールの組み込み準備
   7.5 校正ツールの組み込み
   7.6 校正ツール組み込み後のCircleCIの設定
 8章 reviewdog
   8.1 reviewdogとは
   8.2 reviewdogの使い方
   8.3 CircleCIとGitHubの連携
   8.4 reviewdogのCircleCIへの組み込み
   8.5 reviewdogによる通知
   8.6 reviewdog組み込み後のCircleCIの設定
 9章 PDFの自動生成
   9.1 CircleCIによるPDFの自動生成
   9.2 PDFリンクの通知
   9.3 PDF自動生成組み込み後のCircleCIの設定
10章 限界、そしてその先へ
   10.1 ツールの限界
   10.2 あなたの文章は伝わりますか
   10.3 興味のないことについて書こうと思うな
   10.4 技術同人誌という選択肢
 付録 巨人の肩の上に乗る

『読みやすい技術書を書く技術』という本を技術書典7で頒布しますという記事で、目次の詳細を公開しているので、こちらもぜひチェックしてみてください。

nekopunch.hatenablog.com

技術書典7について

techbookfest.org

おわりに

もしかすると本記事を読んでいる方の中には、技術書典7に向けて最後の追い込みをかけている人もいるかもしれません。そんなあなたに「出ない神本より出るクソ本」という言葉を送ります。読みやすさも大切ですが、あなたの本が世に出るほうがもっと大切です。技術書典7であなたの本が並ぶのをなにより楽しみにしています。

最後にすっごい唐突ですが、表紙を貼っておきますね。この表紙を目印に、ぜひ遊びに来てください。お待ちしております。

f:id:tmknom:20190917001220j:plain